AI provider troubleshooting

Fix a misconfigured AI provider in Bandura (wrong base URL, missing key, a model that can't call tools) using the exact message that names each cause.

Provider setup fails in a handful of predictable ways, and Bandura tries to name the one you hit rather than saying “AI error”. This page maps each message to its cause.

Before anything else: Settings (⌘,, Ctrl+, on Windows/Linux) → Test connection. It sends one tiny completion to whatever is configured and reports the result. A wrong base URL, a stale key, or a model id the endpoint doesn’t serve surfaces in a second or two instead of inside a chat turn or a CI run. A pass reads Connected to <model> - replied "ok".

What the message means

Message	What’s wrong
`No Anthropic API key configured. Set one in Settings → AI.`	Provider is Anthropic and no key is saved. Anthropic is the one provider that can’t work without one.
`This AI provider needs a base URL…`	Provider is OpenAI-compatible and the Base URL field is empty.
`This AI provider needs a model id…`	OpenAI-compatible endpoints have no default model. Name one: `gpt-4o`, `llama3.1`, whatever your endpoint serves.
`Could not reach the AI provider at <url> - …`	The request never got an answer. The tail is the real cause, unwrapped: `ECONNREFUSED` = nothing is listening there.
`The AI provider rejected the API key (HTTP 401)` (or 403)	The endpoint is reachable and the key is wrong, expired, or for a different service.
`The AI endpoint or model was not found (HTTP 404) - check the base URL and model id`	Usually the base URL is missing its path prefix (see below). Sometimes the model id doesn’t exist on that endpoint.
`The AI provider returned HTTP <status>`	Anything else the endpoint said. A 429 is rate limiting; a 400 usually means the model rejected the request shape.
`The provider did not respond within 20 seconds.`	The connection opened and then nothing came back. A big local model on a cold start can genuinely take this long, so retry.
`Anthropic keys start with sk-ant-. Check for a copy slip.`	The paste-time check, and it applies only to Anthropic. Every other endpoint mints its own key format.

The base URL, precisely

Bandura appends /chat/completions to whatever you enter. So the base URL has to include the API path prefix, not just the host:

Endpoint	Correct base URL	The usual mistake
Ollama	`http://localhost:11434/v1`	`http://localhost:11434`
LM Studio	`http://localhost:1234/v1`	`http://localhost:1234`
Groq	`https://api.groq.com/openai/v1`	`https://api.groq.com`
OpenAI	`https://api.openai.com/v1`	`https://api.openai.com`

Dropping the /v1 is the single most common setup error, and it shows up as the HTTP 404 message above. The host answered; it just has nothing at that path. A trailing slash is harmless; it’s trimmed.

”It says it can’t reach the endpoint”

For a local runtime, work down this list:

Is the server actually running? curl http://localhost:11434/v1/models should return JSON. If it refuses the connection, start Ollama (or LM Studio’s local server) first.
Is the model pulled? Check with ollama list. An un-pulled tag is a 404 from the endpoint, not a connection problem.
Is the port right? Ollama is 11434, LM Studio is 1234 by default. Both are configurable, and both change nothing else when they do.

For a hosted endpoint, Could not reach… is nearly always DNS, a proxy, or a corporate TLS interceptor rather than Bandura; the same curl against <base-url>/models will fail too.

”The chat answers but never does anything”

The chat is agentic: it works by calling tools (list flows, read one, run one, check drift). A model that doesn’t support tool calling, or supports it unreliably, will hold a perfectly fluent conversation and never touch your workspace. The tell is an answer that describes what it would do, or one that invents a flow’s contents instead of reading it.

The fix is the model, not the setting. Claude supports tool use; so do the mainstream OpenAI-compatible models. Among local tags, reach for the ones that advertise tool support (llama3.1, qwen2.5-coder and similar); details are in Run a local model with Ollama.

If the chat instead stops mid-task, it may have hit ai.maxSteps, the cap on tool round-trips in one turn (default 16, max 40). Raise it in settings.json if you genuinely need longer chains; it exists so a model that loops can’t run forever.

”The endpoint isn’t OpenAI-compatible”

There’s no protocol detection. Bandura POSTs an OpenAI-shaped body to <base-url>/chat/completions and reads an OpenAI-shaped response. An endpoint that speaks something else answers with a 404 or a 400 rather than anything more helpful.

Two cases worth naming:

A native API that isn’t the compatibility layer. Ollama’s own API is /api/chat; its OpenAI-compatible one is /v1/chat/completions. Point at the /v1 prefix.
A gateway that wants extra headers. Bandura sends authorization: Bearer <key> and content-type: application/json, and nothing else. An endpoint that requires additional custom headers can’t be configured from Settings today.

”Generation fails but chat works”

Expected, and by design. A generated flow is schema-validated before it’s written, so a model that produces almost-right YAML is rejected rather than saving you a broken file. Smaller models fail this more often. Retry, be more specific in the prompt, or switch to a stronger model for generation and back afterwards; keys are stored per provider, so switching costs nothing.

Headless: CLI, CI, and MCP

There’s no Settings view in a terminal, so the CLI and the MCP server read the environment. Most headless “AI isn’t working” reports come down to one of three things:

Nothing is set. ai-action nodes fail with a message saying so, and every other node type still runs. A suite with one AI node doesn’t become a suite that can’t run in CI.
The wrong variable. BANDURA_AI_API_KEY takes precedence over the vendor-specific names; a leftover ANTHROPIC_API_KEY doesn’t override it.
Provider not selected. You rarely need BANDURA_AI_PROVIDER, because a base URL alone selects the OpenAI-compatible adapter and a bare GEMINI_API_KEY selects Gemini. Setting a base URL and expecting Anthropic is the contradiction to look for. Note that an Anthropic key beats a Gemini key when both are exported, so unset the one you don’t want.

The full variable table is in Connect an AI provider, and Run flows in CI has working workflow files.

What still works with no provider at all

Worth knowing before you spend an afternoon on this: everything except the AI features. Editing, running, debugging, import, export, the mock server, the CLI, and (despite the name) self-healing, which is a deterministic comparison against your OpenAPI spec and has never needed a key.

Stuck, or found a mistake on this page? Email [email protected]. A human reads it.