Troubleshooting

Ratel Local has three layers: the agent starts a connector, the connector attaches to the per-user daemon, and the daemon builds a scoped gateway from upstream MCP servers. Check them in that order.

First checks

ratel-local --version
ratel-local daemon status
ratel-local mcp list

The command should print a version number. If the daemon is missing, stopped, or older, run:

ratel-local setup

Then restart the agent and inspect its Ratel entry:

claude mcp get ratel-local

codex mcp get ratel-local --json

cursor-agent mcp list
cursor-agent mcp list-tools ratel-local

Only daemon bootstrap tools appear

When connect cannot attach, it still exposes ratel_daemon_status, ratel_daemon_start, and ratel_daemon_setup.

1. Call ratel_daemon_status to distinguish missing, stopped, and incompatible service state.
2. Use ratel_daemon_start for an installed stopped service.
3. Run the terminal command returned by ratel_daemon_setup when setup is required.

Interactive setup never runs inside MCP stdio.

Connector or daemon failure

Reproduce the connector from the affected project:

ratel-local connect --project-root "$PWD"

The command should print its resolved project scope and attach to the loopback daemon. If it reports a missing token or service, run ratel-local setup.

Use direct serve only to isolate the gateway from the daemon and connector:

ratel-local serve --auto-config --project-root "$PWD"

Stop it with Control-C before reconnecting the host.

Daemon logs live under ~/.ratel/logs/. daemon status also reports stale state when a recorded pid or port no longer answers.

Duplicate Ratel connections

An enabled plugin already supplies the connector. Do not keep a second explicit ratel-local host entry beside it.

Open ratel-local daemon open, choose the affected agent, then use Fix duplicate installation. The repair removes only recognized Ratel entries and preserves unrelated MCP servers.

Use Switch to plugin for an MCP-only installation. The explicit fallback remains until plugin installation succeeds.

One upstream is missing

Ratel Local keeps the gateway available when one upstream fails. Inspect the effective entry and authorization state:

ratel-local mcp list
ratel-local mcp get <name>
ratel-local mcp auth --check

Common causes:

Reconnect the agent after the correction.

Wrong project or scope

The daemon loads these scopes in order:

~/.ratel/config.json
<projectRoot>/.ratel/config.json
<projectRoot>/.ratel/config.local.json

Later scopes replace matching names. Check the registered root and connector resolution:

ratel-local project list
ratel-local connect --project-root /absolute/path/to/project

The connector otherwise checks RATEL_PROJECT_ROOT, CLAUDE_PROJECT_DIR, then its working directory. Set RATEL_PROJECT_ROOT in a manual host entry when the host does not provide a useful project directory.

Run project/local mutations from inside the intended project or pass --project where the command supports it.

Dense retrieval failure

Semantic and hybrid gateway startup fails closed when the model or endpoint is not ready.

ratel-local retrieval status
ratel-local retrieval prepare --scope project

Fix the model, endpoint, or API-key environment, then reconnect the agent. To return to the model-free default:

ratel-local retrieval configure --scope project --method bm25

Use the scope that owns the active override. See Retrieval.

Cloud telemetry is unavailable

Cloud telemetry is experimental and off by default. traces mutations require the running daemon to have RATEL_FEATURE_CLOUD_TELEMETRY=1 persisted in its service definition.

ratel-local traces status
ratel-local daemon status

Exporting the flag before daemon restart does not update an installed service. Reinstall it with the gate:

ratel-local daemon uninstall
RATEL_FEATURE_CLOUD_TELEMETRY=1 ratel-local daemon install

Status stale means the managed exporter points to an old daemon port; traces enable can repair it. Status conflict means another exporter owns the setting. Replacement is irreversible and requires explicit confirmation or both --overwrite --yes.

See Experimental Cloud telemetry before enabling any content-bearing level.

First-run networking

The first exact npx launch may download the package:

npm view @ratel-ai/ratel-local version
npx -y @ratel-ai/ratel-local --version

If either fails, fix registry, proxy, DNS, or certificate access in the environment the host inherits. mcp add can also probe a new upstream for its description; run the upstream command directly when that stage stalls.

Version mismatch

Compare every executable that can win on PATH with the stable package pin used by the plugin or a manual host entry:

which -a ratel-local
ratel-local --version
npx -y @ratel-ai/ratel-local --version

Keep one stable installation path, run ratel-local setup, and restart the host. Stable plugin setup follows the repository's default main branch; remove any branch, tag, or --ref override.

Interrupted changes or legacy state

ratel-local doctor
ratel-local doctor --fix
ratel-local backup list

doctor diagnoses transaction recovery, project state, scoped OAuth state, and legacy skill links. --fix applies only recoverable repairs.

For a manual rollback, inspect the matching ~/.ratel/backups/<timestamp>/manifest.json. Copy each required backupPath to its originalPath; remove a newly created file only when existedBefore is false. There is no general restore command.

Update, reconfigure, or remove

Upgrade the exact global package and re-run setup:

npm install --global @ratel-ai/ratel-local
ratel-local setup

Use setup --agent <agent> to repair a host link. Use daemon uninstall followed by daemon install --port N to change the service port.

For complete removal, follow the ordered flow on Daemon. Service removal preserves ~/.ratel for recovery.

Next steps