Troubleshooting
Most problems are one of four things, and three of them look identical from the outside. Start with one command.
5 min
Run this first
beehaven doctor
It checks Node, the daemon, the relay and a live workspace round-trip, and prints the fix rather than the symptom. If it is happy and something still fails, the problem is in the call rather than the connection — skip to the last section.
The three connection failures
They present the same way. They do not have the same fix.
beehaven status
| It says | Meaning | Fix |
|---|---|---|
| Daemon: NOT running | Nothing owns the local socket. | beehaven start --headless |
| Relay: DOWN — token expired | The process is up; the credential is dead. | beehaven login |
| Relay: DOWN — token valid | The socket dropped, e.g. after sleep. | beehaven restart |
status says the token is valid.“Daemon already running” but nothing works
The process is alive with a dead socket. That is the one case where a restart is the right move.
Two owners, one daemon
If the Clearly Mac app is open, it owns the daemon and the CLI’s start/stop defer to it — quit and reopen the app instead. Only one daemon runs at a time; start --headless refusing is the single-instance guard doing its job, not an error. Not running it? Download for Mac — it keeps the daemon alive and signed in for you.
“My workspace is empty”
Usually the wrong environment.
beehaven env # which backend am I pointed at?
--env is deploy-only. It is not a per-call switch: every call, sql and admin goes wherever the daemon points. So a command that reads like it targeted staging can be reading production, and a workspace that looks empty is often the other environment. Use beehaven env <name>, and an env switch is not live until the daemon reconnects.If the workspace is right but a document is missing, check that you are searching for it the way it is indexed — see Search. A paraphrase can return nothing, with no error.
An MCP client will not connect
| Symptom | Likely cause |
|---|---|
| 403 on a workspace-scoped URL | You are not a member of that workspace, or it does not exist — the same message covers both deliberately, so the endpoint cannot be used to enumerate ids. |
| 401 after it worked before | The credential was revoked, or it names an agent that has since been archived. |
| Connects, but the tool list looks wrong | Your client cached tools/list at connect. Reconnect it — see below. |
| Tools are listed but every call refuses | Scope. A read-only credential lists the same tools it cannot write with. See Security. |
serverInfo.version in the handshake is what tells you which build you are talking to.A call succeeds and nothing happens
Almost always a dropped field.
Unknown keys are stripped by validation rather than rejected, so a misnamed field produces a confident success and no effect. The three that have cost the most:
| You sent | It wanted | What you got |
|---|---|---|
description | body | A ticket with a title and nothing else, and a key back as though it worked |
beehaven explain document-create # the real schema, from the server
explain reads what the server validates against, so it cannot go stale. When a call surprises you, read the schema before changing the payload.
Still stuck
Help is where a person answers; status is where an outage shows. Include the output of beehaven doctor — it carries the version, the environment and which of the four layers failed.