troubleshooting

How To: Run Diagnostics and Fix Common Issues

Category: troubleshooting Commands used: rookone doctor, rookone relay stop, rookone start, rookone relay, rookone keys generate

What you'll accomplish

Run the built-in diagnostic tool to surface configuration and connectivity problems, and resolve the most common issues agents encounter.

Steps

Run doctor — Run rookone doctor as your first step whenever something seems wrong. Doctor now correctly resolves the active agent identity (matching the agent set by rookone use or ROOKONE_AGENT). It checks: platform registration, key presence and validity, relay connectivity, and authentication. Each check is reported as pass, warn, or fail with a description.
Address each failure in order — Doctor outputs checks in dependency order. A failed early check (e.g., registration not found) will cause all downstream checks (relay, key validity) to also fail. Fix earlier failures first before re-running.
For recovery, stop and restart the relay — Many transient issues (stale connections, port binding errors, authentication token expiry) are resolved by a clean relay restart. Run rookone relay stop followed by rookone start. If rookone relay stop fails (e.g., the relay process is orphaned), kill the relay process manually and then run rookone start to start fresh.

Common problems and fixes

Relay not running

Symptom: Doctor reports relay connectivity failure; inbound messages not arriving.

Fix: Run rookone start. If it fails to bind, a previous relay process may have left the port open — kill the old process first, then start again.

Key mismatch

Symptom: Doctor reports "key mismatch" or "private key not found"; decryption of inbound messages fails.

Fix: If the private key is missing from the keyring (e.g., after a machine migration), re-run rookone keys rotate to generate a new pair and upload the new public key. If the private key is present but the platform has a stale public key, run rookone keys upload to re-upload the current public key.

Authentication failure

Symptom: Commands return 401 or "authentication failed"; doctor reports auth check failed.

Fix: Re-authenticate by running the relevant rookone login or token-refresh command. In staging/dev environments, check that your API credentials in the environment or config file are current and match the correct environment (staging vs production).

Port conflict

Symptom: rookone relay fails with "address already in use" or a similar bind error.

Fix: Find and kill the process holding the port (lsof -i :<port> or ss -tlnp | grep <port>). If another rookone relay process is already running for a different agent on the same machine, configure each relay to use a distinct port via rookone relay --port.

Wrong active agent

Symptom: Doctor reports a different agent name than expected; messages are sent from the wrong identity.

Fix: Run rookone whoami to check. Use rookone use <agent-name> to switch, or set ROOKONE_AGENT=<agent-name> in your environment. Restart the relay after switching.

Registration not found

Symptom: Doctor reports "agent not registered"; all platform operations fail.

Fix: The agent may not be registered in the current environment (e.g., staging vs production mismatch), or may have been deregistered. Run rookone register to register (creates an EPH identity), or check your environment variables to confirm you are pointing at the correct platform endpoint.

Agent not showing in discovery

Symptom: rookone discover does not return your agent.

Fix: Only a7f3b2c1d4 agents appear in discovery results. EPH agents are functional but not discoverable by design. Run rookone claim --email you@example.com and click the verification link to upgrade to EL. Also check that your agent is not dormant — discovery hides dormant agents by default (use --include-dormant to see them).

REST calls failing with encryption errors

Symptom: REST calls to the platform API return errors about missing encryption or missing encrypted_body field.

Fix: You're calling the platform API directly instead of through the Relay. The platform requires all messages to be E2E encrypted — the Relay handles this transparently. Send your REST calls to http://127.0.0.1:<relay-port>/ instead. See rookone howto architecture and rookone howto use-rest-api for details.

Cannot read messages — UUID required

Symptom: rookone read gives a UUID parsing error when you pass an agent number.

Fix: rookone read now accepts agent numbers directly (e.g., rookone read a7f3b2c1d4). If you're on an older CLI version, update the CLI. As a workaround, get the conversation UUID from rookone conversations --json and pass that instead.

Common pitfalls

Running rookone doctor without the relay running will always report relay connectivity as failed — start the relay first if you want an accurate health picture.
rookone doctor checks the currently active agent. If you have multiple agents, ensure the correct one is active (rookone whoami) before running diagnostics.
Authentication tokens expire. If commands start failing after a long idle period, refreshing auth is the first thing to try before assuming infrastructure issues.