Troubleshooting
Quick triage
| Symptom | Go to |
|---|---|
| Installation fails or a port is in use | Installation or port errors |
| A provider rejects or lacks a key | Missing or invalid provider key |
| The Agent cannot sign in, or Claude Code or Codex is not installed | Agent sign-in or installation errors |
| Two nodes do not connect | A noodle does not connect |
| A node does not run | A node skips execution |
| A generation fails or takes a long time | Generation errors or delays |
| A saved LLM model changes on load | An old LLM model changes |
| A video does not play or encode | Video or media preview errors |
| A ComfyUI import or run fails | ComfyUI errors |
| A project does not save or recover | Save or recovery errors |
| A result or project is missing | Missing assets or projects |
| A desktop update fails | Desktop update errors |
| Nodes are off screen, or you need to report an error | Find nodes and report an error |
Installation or port errors
If installation fails, check your Node version and the package manager's error message.
The source-install guide uses Node.js 22.12 or newer.
Run npm ci with the repository's existing lockfile.
If browser port 3000 is occupied, start the app with another PORT value.
See the installation commands.
The desktop app uses port 47831 instead.
Its conflict dialog offers Retry, Open Logs, and Quit.
Missing or invalid provider key
- Open Nb → Project settings → Providers.
- Check the key for the node's selected provider.
- Save the settings and retry the node.
Browser-entered keys override environment keys.
If you use .env.local, use the exact variable names from Models and Pricing.
For Replicate and fal.ai, those names are REPLICATE_API_KEY and FAL_API_KEY.
Restart the browser server after environment-file changes.
The Agent uses its own Claude Code or Codex account sign-in. Provider keys enable generation nodes, not Agent access.
Agent sign-in or installation errors
| Status | What to do |
|---|---|
| Tool not installed | Run the installation command shown in the Agent panel, then check again |
| Signed out | Use Open Claude Code sign-in or Sign in with ChatGPT and finish in your browser |
| API billing selected | Sign in with the supported subscription account instead of an API key |
| Subscription unconfirmed | Check the selected account and retry the status check |
| Sign-in failed | Read the panel's error and use its terminal sign-in fallback if offered |
| Plan limit reached | Wait for the plan limit to reset; generation-provider keys do not extend it |
Claude Code needs a paid Claude subscription; Codex needs a ChatGPT plan with Codex access. If a turn stops or fails, queued messages wait for Send now. Closing the Agent window does not stop its turn. See Agent for setup and controls.
A noodle does not connect
- Check the data type on both socket labels.
- Select a model that accepts the available input.
- Drag the noodle to its matching socket.
Some model choices change the available sockets. You can also drag a noodle to empty canvas space and choose a compatible node.
A node skips execution
Missing inputs skip a node instead of disabling Run.
- Check that the upstream node has a result.
- Check the target socket's type and the selected model.
- Check whether an empty input is optional.
- Check whether a Switch disables the path or a group is locked.
An empty optional input also skips downstream nodes that depend on it. Hidden noodles still carry data. A pause noodle stops execution until you select Run again.
Generation errors or delays
Read the node's error before you retry. A rejected key, unavailable model, quota limit, or unsupported input needs a different correction.
| Symptom | Action |
|---|---|
| Missing or renamed model | Use Retry on a provider notice, or Search Replicate / Search fal.ai for other results |
| Request limit | Reduce Max parallel calls in Settings → Node defaults |
| Primary model fails | Check the Fallback tab and its provider key |
| Long video or 3D task | Keep the app open while it polls the existing job |
| Encode must stop | Select Stop; if a repeated run shows Stopping, select it again to stop immediately |
| Provider rejects content | Check the reported restriction and revise the prompt or media |
Long jobs can continue at a remote provider after the editor stops or loses its session. Check that provider's job before you submit it again.
An old LLM model changes
The app keeps supported legacy models for saved workflows. For a retired model ID, the catalog selects a replacement and shows a note. See the legacy model table. If the model ID is unknown, select a current model from the dropdown.
Video or media preview errors
Videos play inside media nodes on hover. An Output node is not required for playback. Video Trim, Video Stitch, and Ease Curve require browser encoding support. If encoding reports unsupported capabilities, use the error text to identify the unavailable codec or API.
For accepted upload types and sizes, see Upload limits.
If external media is missing after load, restore the project media folders to their saved location.
ComfyUI errors
- Open Settings → ComfyUI.
- Check the selected backend, endpoint, and any remote-server authentication.
- For Cloud, check the account key under Settings → Providers → ComfyUI.
- Select Test connection.
- Read the reported error before another import or run.
| Error | What to check |
|---|---|
| Cloud authentication | Enter your platform.comfy.org account key in Providers → ComfyUI |
| Local endpoint unreachable | Start ComfyUI and check its address, normally http://127.0.0.1:8188 |
| Editor-save import fails | The server must provide /api/object_info |
| Missing custom node or model | Install it on the selected backend, or choose a compatible backend |
| API v2 route missing | Disable Behind comfy-api-proxy for a standard ComfyUI server |
| Partner/API node rejects credentials | Set the Comfy API-node key under Advanced |
| Job times out | Check the server job and the configured 1–60 minute timeout |
The default job timeout is 30 minutes. A longer timeout does not install missing models or repair a failed job. See the ComfyUI guide for formats, Blueprints, and previews.
Save or recovery errors
Save the project once before you rely on auto-save. Its directory must remain writable. Check Settings → Project → Save automatically. For auto-save timing, see Project files and auto-save.
- Open Settings → Project.
- Check the project name, location, and Save automatically switch.
- Check free disk space and directory permissions.
- Select Nb → Save project and read any error notification.
If a node crashes, use its inline recovery control. If the desktop server stops, choose Restart Server. If the desktop editor crashes, choose Recover Editor and review the recovery session. Restoration does not resubmit interrupted generation jobs.
If desktop secure storage fails on macOS, unlock the keychain and retry. If Windows credentials become unreadable, the app offers Reset stored keys. Reset preserves the unreadable file and starts an empty store. Enter your keys again after reset. You can also choose Use for this session only. See Desktop app for logs, profile paths, and environment imports.
Missing assets or projects
Recent generations only shows the current tab's recent results. Open Nb → Assets for the full library. If a result appears under Missing files, restore its original media location. If an older project is absent from Open, open Settings → Storage. Under Bring in projects from another folder, select Choose folder…. Choose Leave them where they are to register projects without moving them.
If a folder move fails, read its report before you remove files or try another move. See Assets and Storage for move choices, Trash, and permanent deletion.
Desktop update errors
If an update fails, use the notice's release link to get the installer manually. An unsigned Mac preview cannot update in place. Development runs do not install updates, and isolated test profiles do not check automatically. A downloaded update installs on restart or the next normal quit. Save your work before either action. See Desktop updates.
Find nodes and report an error
If nodes are outside the viewport, select Fit view in the navigator. If the minimap is closed, select Show minimap. The app has no documented fit-view keyboard shortcut.
For a report, include the app version, operating system, failed step, and exact error text.
Browser developer tools show failed requests and console errors.
On macOS, the desktop app provides Help → Open Logs.
On Windows, logs are in %APPDATA%\Node Banana\logs\.
The disconnected-server banner also provides Open logs.
Keep credentials and private workflow content out of the report.
Use GitHub issues (opens in a new tab) or Discord (opens in a new tab).