Troubleshooting

This page is grounded in:

• crates/tui/src/app/update/pickers.rs
• crates/core/src/config/resolve.rs
• crates/cli/src/cmd/oneshot.rs
• crates/provider/src/models/registry.rs
• crates/tui/src/app/update/core_events.rs
• crates/tui/src/app/update/commands.rs
• crates/tui/src/app/update/keys.rs

1) Auth/provider setup issues

Symptom:

• Model picker shows: No connected providers. Run /connect to configure a provider.

Fix:

1. Run /connect in TUI.
2. Or configure [providers.<name>] and [defaults] in ~/.swarmie/config.toml.
3. For API-key providers, ensure the configured api_key_env variable is set.

2) OAuth provider returns unauthorized

Symptom:

• Requests fail with unauthorized/401 behavior after OAuth setup.

Fix:

1. Re-run /connect for that provider.
2. Ensure provider config uses the intended authentication mode.
3. Confirm stored OAuth credentials exist (runtime resolves OAuth credentials from credential store in resolve_runtime_provider).

3) Tools are denied in headless mode

Symptom:

• swarmie prompt prints warnings like permission denied for tool ....

Fix:

1. Expected default: non-interactive runs auto-deny permission requests.
2. For trusted automation only, use --dangerously-bypass-approvals.

4) Model name not behaving as expected

Symptom:

• You pass a model name, but behavior/protocol selection is not what you intended.

Fix:

1. Use /models in TUI to pick from known registry entries.
2. Prefer canonical IDs over ad-hoc names.
3. Remember: unknown names pass through resolve_model_id unchanged.

5) MCP commands show no servers

Symptom:

• Footer hint: No MCP servers configured.

Fix:

1. Add [mcp.servers.<name>] entries in config.
2. Re-open /mcps after config changes.
3. Use /status to verify server states once configured.

6) Session resume doesn’t restore expected history

Symptom:

• Resume reports empty/fresh behavior.

Fix:

1. Use /resume picker or swarmie resume --last.
2. Confirm the selected session actually has stored messages.
3. If no messages are stored, Swarmie intentionally starts fresh.

7) Context or cost grows too high

Symptom:

• Context usage keeps climbing, or session cost is higher than expected.

Fix:

1. Check /status and footer context/cost indicators.
2. Run /compact to summarize and reduce prompt load.
3. Lower thinking level with Alt+T when a reasoning-capable model is active.