Troubleshooting

Start with budgetai doctor — it checks provider setup, memory, search, channels, sandbox posture, and routing, and suggests fixes.

budgetai not found after install

Open a new terminal window, or re-run the PATH step from the install guide. On uv installs, uv tool update-shell refreshes the PATH.

Router pinned to one tier

The on-device router bundle may be missing. Either restore the bundle or switch to the llm_judge strategy, which needs no local model files:

budgetai configure router --router llm_judge

Memory falls back to keyword search

The local ONNX embedding runtime failed to load. On Windows this is usually a missing Visual C++ runtime. Install it, then restart the gateway:

budgetai gateway restart

A channel is not connected

Saving settings is not the same as connecting. Restart and check live status:

budgetai gateway restart
budgetai channels status <name> --json

Treat it as connected only when enabled, configured, and connected are all true.