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.

WhatsApp: “bridge unreachable”

Symptom — WhatsApp shows “bridge unreachable”, “Node.js not found” or “WhatsApp bridge not found at …”, and no QR appears.
Why — the WhatsApp bridge is a small Node.js program the app starts for you. An app opened from the Finder on a Mac doesn’t see the usual install folders for Node, so it can miss Node even when it’s installed. Older builds also looked for the bridge in a folder that only existed on the developer’s machine.
Fix — install Node.js 18+ if you haven’t. Then open Settings → Channels → WhatsApp → ▸ Advanced and enter the full Node path (for example /opt/homebrew/bin/node; run which node in Terminal to find yours). If the bridge still can’t be found, install the latest askTheodor build. Then click 🔗 Pair (scan QR) again. The first QR can take up to 2 minutes.

No reply in WhatsApp’s “Message yourself” chat

Symptom — you write help in the “Message yourself” chat on your phone, and nothing comes back.
Why — commands only work through the phone console, and it only answers numbers you’ve registered. The WhatsApp channel also has to be linked and the computer running it awake.
Fix — open Settings → Channels → 📱 Phone console → Set up. Tick Let my own number/address command the team, add your WhatsApp number under My addresses, and click Save. Check the WhatsApp channel shows ● Linked and is enabled. Replies arrive within a minute. You can test the console first with Try it here. See Phone console.

WhatsApp test send says “no digits”

Symptom — the WhatsApp 📨 Test send button fails with “no digits in recipient”, or says a number “is not on WhatsApp”. From 0.9.283 the button is called 📨 Send test message and stays greyed out until the box holds a phone number.
Why — the box next to that button takes the phone number to send a test to. It isn’t a chat box for your agents.
Fix — enter a full international number, digits only, without + or 00, e.g. 4915123456789. To talk to your agents, write in WhatsApp itself (see above).

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.

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.
WhatsApp bridge — the small Node.js program that connects askTheodor to WhatsApp Web.
Node path — the full location of the node program, set under WhatsApp → Advanced when the app can’t find it.
Phone console — commanding your team from your phone; it only answers numbers you’ve registered.
License — the entitlement that unlocks continued use; the “remote” flag specifically licenses a Team-Hub.