Doctor & troubleshooting
The built-in health check, what it covers, and fixes for the issues operators hit most.
Doctor#
Settings → Doctor runs an on-demand health check across the workspace. It covers things like: is the agent runtime up, are provider keys configured, are there stuck scheduled jobs, did capability downloads complete, is the secrets-key backed up, is an update available, and do the runtime tokens match.
Some checks offer one-click remediation. Escalate posts the result to the COO channel and notifies operators. Doctor is operator-only.
Common issues#
"Can't link new devices" on WhatsApp#
Usually not a bug. Two causes:
- Protocol-version staleness — the bridge fetches the current WhatsApp Web version daily and falls back if offline. If the logged version matches the tracker and it still fails, it's the second cause.
- Account-side link cooldown — WhatsApp throttles new device links after many link/unlink cycles. It clears with time; restarting the bridge makes it worse. Linking a different, untouched number connects instantly and proves the code works.
An agent went silent on a schedule#
A scheduled run can crash mid-execution and leave the job marked "running" forever, so the runtime skips it. The fix is to clear the stuck state for that job and trigger a reload. Doctor's stuck-cron check surfaces this.
Provider key "set" but the agent still fails#
You likely saved it in the Secrets tab. Provider keys must go in Settings → AI & Models → Model Providers to reach the runtime. See Models, providers & secrets.
The desktop app shows an old UI / stale version#
A dev backend already owning the app's port can make the desktop app serve a stale frontend. Make sure nothing else is bound to the workspace port before launching.
The desktop app opened something that isn't damn.dev#
Older builds looked for a running workspace by checking a few fixed ports and trusting whatever answered — so an unrelated app already using :3001 could end up displayed in the damn.dev window. Current builds verify a server is damn.dev before connecting to it, and read the port from the backend itself rather than guessing, so this can't happen. Update the app if you see it.
If you'd rather move damn.dev off the contested port entirely, see running on a different port.
The desktop app is stuck on the splash screen#
It couldn't get a port. The splash says which ones it tried — free one of them, or move the other app, and reopen damn.dev.
Next#
- Data, backups, networking & updates — recovery and updating.
- Oversight & the Registry — spotting gaps before they bite.