Troubleshoot

rig doctor — the readiness report. Reading it, acting on it, and getting Claude to help.

rig doctor

Walks the workspace and emits a list of checks. Each check is ok or not ok; required checks that fail become gaps. Exit code is non-zero if any required gap exists.

rig doctor --json

Same content, machine-readable. This is the format the agent skill reads. Full schema: doctor JSON contract.

Common gaps and how to fix them

Missing env var

✗ env  FINANCIAL_DATASETS_API_KEY  required, missing
  target: .env
  template: scripts/.env.example

Get the value (from the source the README points at) and either:

echo "FINANCIAL_DATASETS_API_KEY=…" >> .env

Or re-run setup:

rig install --env FINANCIAL_DATASETS_API_KEY=…

Missing tool

✗ tool  uvx  required, not on PATH
  install: https://astral.sh/uv

Install the tool (rig won't do it for you) and re-check:

brew install uv     # or whatever your platform calls for
rig doctor

MCP server declared but not working

✗ mcp  yfinance  required, declared in .mcp.json, not launchable
  command: uvx yfinance-mcp-server

The server is in your .mcp.json but uvx yfinance-mcp-server errors. Run the command directly to see what's wrong — often a missing env var, a network issue, or uvx itself is missing. See [mcp].

Missing folder

✗ dir  data/portfolios  required, missing

mkdir -p data/portfolios

Or simply rig install — it creates declared folders.

Collab daemon not running

✗ sync daemon  required, stopped
  remediation: rig resume

See the shared-rig troubleshooting.

Letting Claude do it

If Claude Code is running in the workspace, it's already read .claude/skills/rig/SKILL.md and knows the gap-and-repair loop:

"Run rig doctor and fix what's broken."

Claude will:

Run rig doctor --json.
Walk the gap list.
Ask you for any env values it needs.
Run safe scaffolding (mkdir, write .env).
Re-run rig doctor until clean.

The repair workflow is documented in detail at Repair workflow.

When doctor itself fails

If rig doctor errors out before producing a report:

Manifest invalid — run rig doctor --json and read the parser error. Compare against the manifest reference.
Permission denied on .claude/ or .rig/ — fix the file mode.
Outdated CLI — rig --version; upgrade with npm install -g @rigxyz/cli@latest.