Troubleshooting guide

Troubleshooting should preserve evidence and avoid hidden fixes. If a setup problem changes operating authority, fix it through the normal ROST workflow.

Reading command errors (start here)

Every command failure returns a structured error you can act on — you should rarely see an opaque "internal error" for a known state:

• code — a stable machine code. A known business precondition (for example a manifest that is not yet signed, or a dry run that has not passed) returns COMMAND_PRECONDITION_FAILED (HTTP 409), not a 500.
• message — a readable explanation of what was not satisfied.
• help — the exact next command to run. On a failure, read the `help` field and run the command it names — do not retry the same call blindly. The CLI also prints it as a → try: … line.
• requestId — quote this when reporting a genuine internal error (the only thing a real 500 returns; it never leaks internal detail).

Before calling a command that changes state, discover its exact shape so you do not guess the JSON: rost command schema <id> (or rost_describe_command) returns the input/output JSON Schema, the help pointer, and a validated worked example; rost command list (or rost_list_commands) enumerates the surface.

Common checks

• Onboarding seems stuck: call onboarding.status / rost_onboard_status and inspect missing graph, Charter, Compass, or staffing steps.
• Graph looks wrong: read graph.get / rost://graph to confirm seat ids, parents, and occupancy before mutating.
• Agent cannot act: check the Charter, permission manifest, Steward chain, and token scope with agent.status / rost_get_agent_status and seat.get.
• Agent looks incomplete: open the fleet row on /agents and follow the configuration readiness links for the missing Steward chain, lane/substrate, credentials, tools, model config, sandbox dry run, or go-live state.
• Signal looks wrong: read signal.list / rost_list_signals and check owner seat, cadence, target, and evidence.
• Friction is noisy: read friction.list and check whether the underlying Charter or measurable is unclear.
• Escalations are aging: read escalation.list / rost_list_escalations; a human resolves through the Steward queue.
• MCP access fails: revoke and recreate the narrowest token after checking scope (mcp_token.revoke then rost mcp install --client <client> --scope seat --seat-id <seat-id>; standalone mcp install requires an explicit --scope).
• Settings section unavailable: keep the route open, read which section is marked unavailable, and retry or fix that source directly. Do not treat a missing Settings panel as permission to write blind values; budget and Sync Brief settings stay read-only until their data loads.
• Org-intake upload failed: read the safe parse status and reason, then ask the human for a better source file or continue by chat. Browser org intake accepts bounded CSV, text, PDF, DOCX, XLSX, PNG, and JPEG files; extraction failures are retryable and should not be worked around by pasting raw binary, stack traces, secrets, or full customer exports into a prompt.
• "Invalid persisted document" on a Compass read: a legacy or imported row failed the current Compass schema. Every surface names the violated constraint and field path (for example principles.0.value: Invalid input: expected string, received undefined) from the SAME bounded summary, but each surface exposes it through a different field — read the one that matches where you saw the error, not another surface's:
• compass.approve_version (or any command failing on the same read boundary): the command's message and details.issues.
• The /compass page: the invalid-draft banner's own text (backed by CompassVersionView.issueSummary, not a JSON field you read directly).
• An agent's context or MCP get_context: a "Compass unavailable" notice folded into the agent's system prompt (agent runtime), or the compass_issue_summary field (MCP).

All four are bounded to a fixed length so one badly corrupted row cannot flood a log line or a model's context — a document with an unusually large number of failures ends with an explicit ...and N more issues count rather than silently dropping the rest, and an unrecognized key NAME is redacted (shown as [redacted]) unless it is provably an ordinary field name, since a malformed row can carry credential-shaped material as a JSON key. Repair by publishing a new Compass version through the normal draft-and-approve flow (compass.draft then compass.approve_version) — never by editing the stored document in place.

Surface-specific failures

• "Not logged in" or 401: run rost login, then rost whoami.
• "Wrong tenant": rost tenants then rost use <tenant-slug-or-id>.
• "Command denied by scope or manifest": a seat token cannot run tenant-admin setup. Switch to a tenant-admin token, or ask a human Steward to update the seat Charter and permission manifest.
• "Confirmation required": the command is gated. The CLI prints rost command confirmation.approve --json ... or a web link. A human approves; an agent does not approve its own request.
• Revoked, expired, or invalid MCP token: run rost mcp install --client <client> --scope <tenant-admin|seat> again to mint and register a fresh one (standalone install requires an explicit --scope), or rotate with --rotate <old-token-id> (rotation inherits the old token's scope, so no --scope needed). Tokens minted by mcp install default to a 90-day expiry — check expires_in_days in rost command mcp_token.list.

Agent-creation failures

These are the common blockers when adding an agent (see the add-agents guide and the custom agents guide):

• Missing Steward: an agent occupancy or go-live is blocked because no Steward chain resolves to a human. Use the inline steward-chain fix when the builder offers a human-occupied candidate, or name a human Steward on the seat, then retry. The no-orphan-agent rule is enforced server-side; do not route around it.
• Failed dry run: the draft is kept and the failure reason is shown. Read it with agent.status / rost_get_agent_status, fix the Charter, manifest, or tool decision, then agent.run_dry_run again. A passed dry run is required before go-live.
• Declined tool: declining a proposed tool updates the permission manifest and the dry-run task. If the agent then cannot complete the task, either grant a narrower tool or adjust the Charter so the work still routes safely or escalates.
• Expired confirmation: a pending human gate expired before approval. Re-issue the gated command (for example agent.create_from_template, charter.sign_manifest, or agent.go_live) and approve the new confirmation; an agent never approves its own request.
• Runner offline: a Local Runner lane agent cannot run because its Runner is offline. Check state with runner.list / rost_list_runners; bring the Runner back or re-pair it with runner.pairing.start. Scheduled runs should surface as Friction or escalation, not fail silently.
• Token revoked after go-live: a live agent shows degraded because its credential or MCP token was revoked. Re-mint the narrowest token with rost mcp install or re-ingress the credential through the vault path; scheduled runs fail toward Friction/escalation until it is restored.

When to stop for confirmation

Most reads are safe to run while diagnosing. Any fix that changes authority, credentials, go-live state, or a durable decision is gated — human_required, credential_flow, or dangerous — and routes through a human confirmation (confirmation.approve). Diagnose freely; stop before approving.

Agent guidance

Name the failing surface, collect evidence, recommend the smallest correction, and escalate when the fix changes authority, credentials, or go-live state. Never paste secrets into chat or tool arguments while troubleshooting.