Troubleshooting
Fix the common problems, find out what went wrong, and share the right details with support.
Start by asking Oktapod. Questions such as "Is everything set up?" are answered from its own setup and connection state. If chat itself is not working, use the terminal on the computer that runs Oktapod:
oktapod checkupcheckup runs the health checks and names the next fix. Run it again after
every fix.
Common problems
| Problem | Fix |
|---|---|
| The web app says the browser is locked | The address works but this browser has no valid key. Run oktapod ui --open on the Oktapod computer, or paste the key from oktapod ui into the unlock card. |
| The web app does not load at all | Run oktapod status. If Oktapod is stopped, run oktapod up. |
| "Connect a model to start chatting." | No AI account is connected. Run oktapod onboard, or connect one in System setup. |
| Replies fail after working before | The AI sign-in may have expired. Run oktapod auth status, then oktapod auth login --provider <provider>. |
| An app connection stopped working | Open its card under Connections and sign in again. If sign-in is fine, check the provider's billing or plan. |
| Messages from a channel do not arrive | Run oktapod channels verify --channel <id>. New senders need an approved pairing code; see Messaging channels. |
| A reminder or brief did not arrive | Check quiet hours first, then the delivery channel's status with oktapod channels status. |
| Work looks stuck | It may be waiting for you. Check Approvals or oktapod approvals pending. Waiting for a person is not a failure. |
| A reply seems to come from another chat | Start a New chat. Channels and chats are kept separate on purpose. |
| "Another process is using the port" | Run oktapod runtime repair, then oktapod up. It never stops a program it does not own; it tells you how to find it. |
| The phone app cannot connect | Check the address is HTTPS and reachable from the phone. On Tailscale, keep the Tailscale app connected. |
The diagnostic toolkit
| Command | Tells you |
|---|---|
oktapod status | Whether Oktapod is running and reachable. |
oktapod checkup | Health and readiness, with the next fix. --verbose for detail. |
oktapod doctor | Configuration, storage, service, and provider diagnostics. |
oktapod reliability:status | The last failure, the repair path, queue depth, and latency. |
oktapod logs tail | Recent log lines. Add --service core or --service gateway. |
In the web app, Settings → Advanced → System health shows the same checks, and Support shows readable checks with raw details behind Details.
doctor --repair and checkup --repair apply the repairs Oktapod knows are
safe. They never pick new credentials, reverse a policy decision, or delete
your data.
Look at one run
Every piece of work has a run ID, shown in the web app's work receipts and in
oktapod runs tail. To see what happened:
oktapod timeline <run_id>
oktapod decision <run_id>
oktapod inspect <run_id>timeline shows each step, decision shows why it was allowed or blocked,
and inspect shows the context. All three leave out secrets and prompt text.
Restart and repair the service
oktapod restart
oktapod service audit
oktapod service repairUse oktapod restart rather than restarting the system service by hand. On a
Mac, if the service is installed but not loaded, oktapod doctor loads it
again, unless you deliberately disabled it.
Sharing details with support
Include the approximate time, the Oktapod version (oktapod version), run IDs,
and the reason codes from checkup. Do not send access tokens, API keys, raw
prompt logs, backups, or database files unless a secure support channel asks
for them.
Full prompt logging is off by default. Turn it on only for a short investigation, and off again afterwards:
oktapod prompt-logging statusBigger recoveries
Restoring a backup, resetting history, rolling back an update, and recovering a damaged database are covered in Backups and operations. Back up before any of them.