Troubleshooting

Start with the bus host:

node dist/cli.js doctor --session <name>

unacked shows waiting mail; last_seen shows when the session last registered or read its inbox.

Push shim messages

The shim logs to stderr. Claude Code shows MCP server logs under /mcp.

Message	Cause	Fix
no session name; push idle	No --session, no SESSION_BUS_NAME, or an unexpanded ${...}.	Normal in a plain claude. For push, start with claude-push.sh.
invalid session name "<value>"; push idle	The name fails ^[a-z0-9][a-z0-9._-]{0,63}$.	Use a lowercase name.
exit 2, BUS_URL must be a base URL ...	BUS_URL missing, or ends in / or /mcp.	Use https://<bus-host>.<tailnet>.ts.net:8443.
exit 2, SESSION_BUS_TOKEN_CMD failed	The command failed, timed out (15 s), or printed nothing.	Run the command yourself; check op access.
exit 2, no token; ...	Neither token variable is set.	Fix the bus-push entry.
exit 2, token rejected (401)	Token unknown, revoked or expired, or principal disabled.	Rotate the token, restart claude.
exit 2, token lacks scope (403)	Token missing bus:read or bus:write.	Mint with --scopes bus:read,bus:write.
exit 3, already has a running shim (pid N)	Two sessions on this machine with the same name.	Use a different name.
exit 4, owned by another principal	NAME_TAKEN.	Pick another name, or session release <name> on the bus host.
bus error (...); retrying in N ms	Bus unreachable or 5xx.	Retries up to every 60 s. Check the bus host.

"Channels are not currently available"

Claude Code ignores the channels flag while both DISABLE_TELEMETRY and CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC are set (seen on 2.1.312). scripts/claude-push.sh clears both for its process. If you launch claude yourself, clear both:

env -u DISABLE_TELEMETRY -u CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC \
  SESSION_BUS_NAME=laptop-api claude --dangerously-load-development-channels server:bus-push

Also clear them in any env block of your Claude Code settings; the script does this with --settings.

Push never arrives

1. Was the session started with --dangerously-load-development-channels server:bus-push and a name? Ask it "what bus session are you?".
2. Is the sender's principal allowlisted? By default only the shim's own principal is pushed.
3. Any startup warning that channels are blocked by policy (channelsEnabled)?
4. If a newer Claude Code does not register the channel, try launching it with MCP_SDK_GENERATION=v1.
5. Pull always works: ask the session to check its inbox.

NAME_TAKEN

Another principal owns the name. Choose another, or on the bus host:

node dist/cli.js session release <name>

This also deletes that session's unacked mail.

401 and 403

• curl -X POST .../mcp without a token returns 401. That is correct.
• 401 with a token: unknown, revoked, expired, or the principal is disabled. Check token list.
• 403: the token lacks a scope, or the client called a method or tool that is not allowed.
• bus not connecting in /mcp: run the headersHelper command by hand. It must print {"Authorization":"Bearer ..."}. If op read fails, the service-account variable is likely missing or cannot read the vault.

Stale sessions and full inboxes

• A session not seen for 7 days is hidden from list_sessions and skipped by broadcast. Use include_stale: true to see it.
• Its owner can unregister it once its mail is acked. An admin can session release <name> regardless (deletes unacked mail).
• INBOX_FULL: the recipient has 1000 unacked messages. Ack them, or release the session.

serve will not start

Exit	Message	Fix
2	refusing to bind <host>	Use 127.0.0.1, or the address from tailscale ip -4 with tailscale on the PATH.
2	invalid BUS_PORT	Use a number from 0 to 65535.
3	serve already running (pid N)	Another serve (or restore) uses the same BUS_DB.
1	cannot listen on ...	The port is taken by another program.

After a Node upgrade

Under nvm, the absolute node path in the unit and in the bus-push entry changes. Re-run install-unit.sh and setup-client.sh.