Troubleshooting

Most Bandura problems announce themselves with a specific message rather than a generic failure. Each heading below is one of those messages, in the order you are likely to meet them: a parse banner, a warned node, a request that will not connect, an assertion you disagree with, and an AI provider that will not answer.

A red banner says the file can’t be parsed

The YAML has a syntax or schema error, and the banner carries the parser’s message. Fix it in the Code tab; Run and Heal… stay disabled until the file parses, and the graph won’t render a guess. Common causes: inconsistent indentation, a routing field pointing at a node id that doesn’t exist, a missing type or config.

A node has a ⚠ badge / Run says “Run anyway”

The node references a variable with no value. Bandura caught it before the run instead of letting a request go out with undefined in the URL. Click the node, open its Variables tab, and either fill the source (.env, environment, flow variable) or type a local override. Details: Variables & environments.

A request node fails and I don’t know why

Click the red node → Result tab. The Request sub-tab shows exactly what was sent (every variable resolved); the Result sub-tab shows what came back. Between the two, the cause is usually visible in seconds: wrong host, missing header, unexpected status. The full debugging walk-through: Run a flow & debug failures.

It works when I run the whole flow, but not from the node I’m on

▶ From here starts a fresh run at the selected node, so nothing earlier has happened: no captured variables, an empty cookie jar, no cached auth token. A skipped login is the usual culprit, and it rarely looks like one. It comes back as a 401, a 403, a 200 carrying an empty list, or a capture that fails a few nodes later, all of which read as a broken endpoint.

The console names the skipped nodes and warns about the jar and the token cache at the top of the run, before the failure it explains. If you need the earlier steps, run the whole flow, or set a breakpoint on the node you care about and press Continue when it stops there.

The “Run failed” notification vanished before I read it

Hovering a notification pauses its dismissal timer, so it stays as long as your pointer is on it. If it’s already gone, nothing is lost: View log on the notification and the run-status segment in the status bar both open the Console at that run, and the failing node keeps its red ring and its Result tab.

The second line of that notification names the failing node and the reason, whether that’s an assertion’s expected-vs-actual, an HTTP status, or the real network cause. If you’re seeing several identical failures, they collapse into one row with a ×N count rather than stacking.

Tests that passed for months suddenly fail

If the API changed underneath the flow (a renamed path, a changed method, a newly required parameter), click Heal… and compare against your OpenAPI spec. It lists the drift and fixes it per finding: Self-healing.

AI features say a key is missing

Generation, chat, and ai-action nodes need a configured provider: Settings (⌘,) → AI provider, then paste a key under API key and Save key. The key goes into your OS’s encrypted store, not into any file you can read. If you’re on the OpenAI-compatible provider, check the Base URL too. If it points at a local Ollama or LM Studio, no key is needed at all, only a running server.

Test connection in the same panel sends one small message and reports exactly what’s wrong, which beats guessing between a bad key, a bad URL, and a model id the endpoint doesn’t serve. Every message it can return, and what each one means, is in AI provider troubleshooting. Start there for a 404, a chat that talks but never acts, or an endpoint that turns out not to be OpenAI-compatible.

Note self-healing is not an AI feature; it works offline with no key.

My settings.json edits aren’t doing anything

Settings apply the moment the file is saved. That includes colours, which repaint the app, the code editor and the terminal at once. If nothing happened, it’s one of these:

• The file doesn’t parse. Bandura falls back to the defaults until it does, and it never rewrites your file to “fix” it. Editing from inside the app (Preferences: Open Settings (JSON)) shows the parse error inline and refuses to save invalid text. Comments are allowed in this file; trailing commas are not.
• The value is out of range or the wrong type, so it fell back to the default. Numbers are clamped to their nearest legal value instead; check the ranges in the key table.
• The key name is wrong. Unrecognized keys are kept, not deleted, so a typo sits there looking correct and doing nothing. The keys are dotted and case-sensitive: ui.fontSize, not ui.fontsize.
• A theme token name is wrong. Only the 22 names in Customize the theme are recognized; an unknown one is ignored on its own while the rest of your overrides apply.
• You put a colour in ui.accent that isn’t hex. rgb() and hsl() work in ui.themeOverrides but not there; that key takes a preset name or a hex value.

An Insomnia export is refused, or imports as nonsense

Bandura reads the Insomnia v4 JSON export. A v5 export is a different format, and it is turned away by name rather than half-read:

This is an Insomnia v5 export (“type: …”), which Bandura cannot read yet.

Choose the v4 JSON format when exporting if your version of Insomnia still offers it. If it does not, export an OpenAPI spec of the same API instead, which imports cleanly and is the better long-term source anyway, because it describes the API rather than one person’s saved requests. More on what each format becomes: Importing.

Bandura says a new version is available

The update notification is a link, not an installer, until you ask for one. What happens next depends on how Bandura was installed:

• Windows, and Linux from the AppImage: Download, then Restart to apply it. Nothing is downloaded before you press the button unless you turned on updates.autoDownload, and nothing installs while you are working.
• Linux from a .deb: there is no in-app update path, so Bandura says so and points you at installing the new version the way you installed this one.

To stop the automatic check entirely, set updates.checkOnStartup to false. With it off, and with no AI provider configured, Bandura makes no network request at all. The manual Help → Check for Updates… always answers either way, including when it fails and why, because silence on that path reads as broken.

A banner says the file changed on disk

Another program (or a git pull) modified a file you have unsaved edits in. Bandura never merges silently: Reload takes the disk version and discards your edits; Keep my edits keeps yours (saving will overwrite the disk version). With no unsaved edits, files refresh automatically.

A command in the terminal won’t stop

Ctrl+C reaches the running command as a real interrupt, and so does the Interrupt button. A program that ignores it (or a shell that has genuinely wedged) needs Restart, which ends the session and opens a new one at your workspace root. Note that Restart takes everything running in that session with it, so check what is in flight first: The built-in terminal.

Where is my data, exactly?

• Flows and specs live in your workspace folder, and nowhere else.
• Secrets are in your .env (git-ignored) and, for AI keys, your OS’s encrypted store (Keychain / DPAPI / libsecret), one per provider.
• Your licence key sits in the app’s own config file, alongside your preferences. Not encrypted, on purpose: it has to survive a machine move and be quotable in a support email.
• Run history, breakpoints and local overrides go to a local profile on your machine, outside the workspace, never committed.
• settings.json shares that same local profile directory. Nothing secret is in it, so it’s safe to copy between machines.
• Nothing syncs to a cloud, and no account exists to sync it to.

Still stuck?

Help → Send Feedback… composes the report for you, with the diagnostics already gathered: your version, platform, and a tail of the error log. It opens the message in your own mail client and sends nothing by itself, so you can read every line, edit anything you would rather not share, and decide whether to press send. Credential-shaped text is stripped before the draft is built, not after you see it.

Or email [email protected] directly with what you tried and, if you can, the flow’s YAML; it’s plain text, which makes helping fast.

If the trouble is specific to an AI provider, the AI provider troubleshooting page maps each message to its cause. For a failure you want to reproduce from a terminal rather than the UI, run the same file with the bandura CLI.