Troubleshooting

Most snags in askTheodor have a quick, known fix. This page lists the common ones, each framed the same way — Symptom (what you see), Why (what’s going on), Fix (what to do). If your issue isn’t here, ask Theodor in a Chat; he can often diagnose it from your workspace.

A worker gives empty replies or “can’t call tools”

• Symptom — a worker replies with nothing, or you see a banner like “this model can’t call tools,” and it never actually searches, reads files, or does work.
• Why — either no AI provider is connected, or the worker is pointed at a model that doesn’t support tool-calling. Without a working, tool-capable model behind it, the worker has nothing to think with and nothing to act with.
• Fix — connect at least one provider (a cloud key, a local runner like Ollama, or the built-in model) in Settings, and make sure the worker uses a tool-capable model with its tools enabled. Then retry the message.

A run seems “stuck” and isn’t moving

• Symptom — a chat or a Plan task sits there, spinner spinning or just silent, and nothing progresses.
• Why — a run can stall (a flaky provider call, an interrupted step). askTheodor detects this rather than leaving it hung forever.
• Fix — look for the Resume banner in the conversation and click it to continue. For background work, the stuck-task watchdog also notices stalled tasks and nudges them; give it a moment, or open the task and resume/retry it. If a whole Plan is paused, reopen it from Plans and resume.

A run is blocked by a budget hard-stop

• Symptom — work stops and you’re told a budget or spending limit has been reached; new runs won’t start.
• Why — you set a money ceiling (global or per Company) and it’s been hit. The hard-stop is doing its job: stopping spend from running away.
• Fix — raise or reset the relevant budget, or wait for its period to reset, then re-run. If this keeps happening, the limit may be set too low for the work — adjust it deliberately rather than repeatedly bumping it. (See Security & privacy for how budgets work.)

Peers can’t reach this machine (delegation/sync fails)

• Symptom — a paired instance shows offline or won’t accept delegated work; sync-pull or key-push to it fails.
• Why — outbound sync/report works over normal internet, but for another instance to reach into this one it needs an inbound URL. If the tunnel or reverse proxy is off — or the Fleet port is taken — peers can’t connect.
• Fix — bring the tunnel/reverse proxy back up (e.g. cloudflared / ngrok) so the machine has a reachable address. Check the runner’s start log: it prints the address it bound to and a loud error if the port was already in use. If so, free the port or move it with ASKTHEODOR_FLEET_ADDR. Full setup is in Deploy to a VPS.

A Library item’s refresh is stuck on “pending”

• Symptom — a Library item set to auto-refresh shows a pending refresh that never seems to apply.
• Why — by design, each auto-refresh is held for your approval rather than applied silently, so a changed source can’t quietly alter your knowledge base.
• Fix — open the item and approve the pending refresh, or hit Refresh now ▶ to pull immediately. If you’d rather it apply automatically in future, turn Auto-approve on for that item. See Library.

My trial ended

• Symptom — askTheodor tells you the trial has expired and gates the app (or, on a hub, reports no entitlement).
• Why — the free trial period is over; continued use needs a license.
• Fix — activate a license on the machine. For a Team-Hub, get the “remote” entitlement onto it — either push the license from a Command Center (Fleet/Peers panel) or add it over SSH — as described in Deploy to a VPS.

Hub licensing is currently lenient

Right now a Team-Hub reports its licensing state but runs anyway (pre-production), so a server can keep working while you sort licensing out. Enforcement switches on later — see the deploy page.

Still stuck?

Open a Chat with Theodor, describe the symptom, and let him investigate — he can read the relevant state and often points straight at the cause.

Terms in this page

• Provider — the company or program supplying the AI model (OpenAI, Anthropic, Ollama, the built-in engine, …); a worker needs one connected to do anything.
• Tool-calling — a model’s ability to invoke tools (search, files, browser); some models lack it, which causes “can’t call tools.”
• Resume banner — the in-chat prompt that lets you continue a run that stalled.
• Stuck-task watchdog — the background check that spots stalled tasks and nudges them along.
• Budget — a money ceiling (global or per Company) on worker spending.
• Hard-stop — the automatic halt that blocks new runs once a budget is reached.
• Tunnel — a service (e.g. cloudflared, ngrok) that gives a machine a reachable inbound URL so peers can connect.
• ASKTHEODOR_FLEET_ADDR — the environment variable that moves the port a hub’s Fleet server listens on, useful when the default is taken.
• Auto-refresh / Auto-approve — a Library item’s scheduled re-pull; refreshes wait for approval unless Auto-approve is on.
• Trial — the free evaluation period before a license is required.
• License — the entitlement that unlocks continued use; the “remote” flag specifically licenses a Team-Hub.