Every entry here was observed in a real run, not hypothesized. Commands run from the repo root.
| Symptom | Meaning and fix |
|---|---|
clawdi auth status looks fine but writes fail |
You parsed the exit code; it is 0 even logged out. Parse "authenticated" from clawdi auth status --json. |
Agent missing from clawdi doctor |
Re-run clawdi setup --no-daemon. Trust the "Environments" line, not per-agent checkmarks. Note: doctor exits 1 whenever any row fails (e.g. Codex simply not installed) — parse rows, not the exit code. |
One agent fails registration with API error 500 while the others succeed |
The batch route is broken for it. Retry once, then register it alone: clawdi setup --no-daemon --agent <type> — the targeted route works where the sweep 500s (observed with Hermes). Then attach the vault to the env project the registration created. |
Doctor shows OpenClaw "detected" but openclaw command not found |
Detection keys off the ~/.openclaw directory, not the binary. Nothing to wire locally — skip openclaw mcp set, treat OpenClaw as hosted-only on this machine. |
A one-shot agent check (hermes -z …) reports memory contents that don't match clawdi memory search |
One-shot modes may not load MCP toolsets and can improvise plausible-looking results. Anchor the check: have the agent run clawdi memory search … --json via its terminal tool and print raw output verbatim; trust only what you can cross-check. |
| Sessions you didn't expect appear in the cloud dashboard | The background sync daemon mirrors every session of every registered agent. Remove it (clawdi daemon uninstall) and push explicitly instead: clawdi push --modules sessions --agent <type> from the repo root is project-scoped — except Hermes, which ignores project filters (all-or-nothing). The setup guide registers with --no-daemon for exactly this reason. |
Daemon users only: restart says "no daemon unit installed", or status shows version drift |
clawdi daemon install once, then clawdi daemon restart after CLI updates. |
| A researcher tick files nothing, exits instantly | Its model provider is out of usage — the most common failure in practice. Check hermes status (or the hosted agent's session log); add usage or configure a fallback provider. |
| Hosted agent can't get skills | Publish with clawdi skill add skills/<name> -p personal -y (the -p personal is mandatory), then in the box: clawdi pull --modules skills -p personal --agent openclaw. If the pull route is gated on your platform version, fall back to npx skills add <repo> -g --copy in the box and copy into ~/.openclaw/agents/main/skills/ — --copy matters, OpenClaw silently skips symlinked skills. |
| Hermes ignores injected env | ~/.hermes/.env overrides process env — remove the clashing key. |
| Symptom | Meaning and fix |
|---|---|
ADDRESS_NOT_ON_CHAIN |
Fresh wallet — foc-cli wallet fund, then foc-cli wallet deposit 1. |
FUND_FAILED: Rate limited. Try again in N seconds |
The hint is misleading: N starts at 30–60s but the real faucet window is ~1 claim per address per day (N can jump to ~80,000). Don't retry-loop. Fund manually — tFIL: faucet.calibnet.chainsafe-fil.io; USDFC: forest-explorer.chainsafe.dev/faucet/calibnet_usdfc (browser challenge, human step) — then re-run foc-cli wallet deposit 1. |
FUND_FAILED: Cannot read properties of undefined (reading 'ServerError') |
foc-cli mangling a faucet refusal — same situation as the rate limit above; treat it identically. |
WALLET_NOT_CONFIGURED |
No wallet on this machine — foc-cli wallet init --keyRef clawdi:FILECOIN_PRIVATE_KEY. |
KEY_REF_PROVIDER_MISSING |
A reference is configured but clawdi isn't on this process's PATH (a GUI-launched agent often has a shorter PATH than your shell). Install it, or fix the PATH. |
Failed to resolve the wallet key from clawdi |
Not authenticated (clawdi auth status --json → parse the field, not the exit code), or the vault isn't attached to the project being resolved against. References are per-project and don't transfer between machines — pin one with --keyProject. |
WALLET_ALREADY_CONFIGURED |
wallet init refuses to discard the configured key. Inspect it first (foc-cli wallet balance --json); --force is a deliberate, human decision — it may destroy the only copy. |
| Upload fails with a network error while retrieval works | Provider ingest outage. Don't blind-retry: check foc-cli wallet balance, wait, re-run. Never index a receipt for an upload that failed — that poisons every agent's recall. |
UPLOAD_FAILED |
May still have stored the bytes. Check foc-cli dataset details before retrying, or you pay twice for the same piece. |
partially_uploaded / errors on a secondary copy |
Flaky secondary provider; the primary copy is stored. Default to --copies 1. |
Error envelope with retryable: true |
Back off (2s / 10s / 30s) and re-run. Never blind-retry fund-moving commands — check wallet balance first. |
Config holds a raw privateKey |
A pre-existing foc-cli config from before the vault setup. Typical locations: ~/.config/foc-cli-nodejs/config.json (Linux), ~/Library/Preferences/foc-cli-nodejs/config.json (macOS), %APPDATA%\foc-cli-nodejs\Config\config.json (Windows). Confirm the wallet holds nothing you need before switching modes — it is the only copy. |
| Symptom | Meaning and fix |
|---|---|
| Recall finds no receipt for a topic | By contract you say so and stop — never substitute a near match. Semantic search returns hits for any query, so require the receipt's topic: to match. Check the spelling; one receipt per topic is the invariant. |
| Recall fails byte validation | Stop everything. The index and the blob disagree; the blob (hash-addressed) is the source of truth. This is the one alarm that matters — investigate before storing anything else. |
| Duplicate or conflicting notes pile up | Run the consolidation pass (memory-consolidator); it resolves contradictions and prunes merged notes. |