Operations

Troubleshooting#

Work the chain in order. Most problems are one of the first three checks.

The three commands#

clawmetry status      # is the daemon alive and ingesting?
clawmetry runtimes    # was anything detected?
clawmetry diagnose    # why does it think it is on this tier?

The dashboard is empty#

The daemon is the answer roughly nine times in ten. The dashboard reads through it and shows nothing on its own.

clawmetry status
# daemon: not running  →  clawmetry sync

If the daemon is running but pages are still empty:

DEBUG=1 clawmetry sync --foreground

Read what it says. It will tell you which runtimes it found and what it did with them.

Then check the store has anything at all:

curl -s localhost:8900/api/local/health | jq
curl -s 'localhost:8900/api/local/sessions?limit=5' | jq '.rows | length'

A runtime is not detected#

Detection is a filesystem check, not a PATH check. Almost always the store has been relocated.

clawmetry runtimes --json | jq '.runtimes[] | select(.id=="<runtime>")'

Then set the override from that runtime's reference page. The ones that catch people most:

Detected, but no sessions#

CLAWMETRY_FAMILY_SESSION_LIMIT=500 clawmetry sync --restart

Raising the limit alone may not backfill: the daemon tracks a high-water mark per source, and a cycle that already decided it was caught up will not revisit that ground. Restart after raising it.

Sessions appear, but cost is zero or missing#

First: is it genuinely unknown, or genuinely zero?

curl -s 'localhost:8900/api/local/sessions?limit=20' \
  | jq '.rows[] | {session_id, cost_usd, cost_status, model}'

PicoClaw persists no tokens at all. Cursor persists none locally. Those are unavailable by design. → What each runtime exposes

Sync is stalled#

clawmetry status --json | jq '{last_sync: .daemon.last_sync, age: .daemon.last_sync_age_secs}'
DEBUG=1 clawmetry sync --foreground

Common causes:

• A very large first pass. A long history takes a while. sync-progress

shows how far it has got.

• Memory pressure on the machine. DuckDB keeps a buffer pool, and a swapping

machine makes the store look slow when it is fine. Check actual memory pressure before tuning anything.

• A runtime store that is locked or unreadable. The daemon logs it and moves

on, so look for the warning rather than a crash.

The store will not open#

clawmetry verify-integrity --json
curl -s localhost:8900/api/local/health | jq

A store reported as invalidated after an abrupt kill usually needs compaction rather than deletion. Always stop the daemon cleanly — clawmetry sync --restart, not a kill — because a kill mid-write is how this happens.

If it is unrecoverable, the store is rebuildable: delete it and re-sync. You get back whatever the runtimes still have on disk, bounded by the session limit.

clawmetry sync --restart          # stop it properly first
cp ~/.clawmetry/local_store.duckdb /tmp/broken-store.duckdb   # keep a copy
rm ~/.clawmetry/local_store.duckdb
clawmetry sync

MCP tools return errors#

→ Connect the MCP server

Cloud sync is not working#

clawmetry status --json | jq '{cloud, endpoint, last_push}'
curl -s localhost:8900/api/cloud-status | jq
curl -s localhost:8900/api/sync-progress | jq

Something looks locked#

clawmetry diagnose --json | jq
clawmetry runtimes --why <runtime_id>
clawmetry features --why <feature_id>

diagnose prints every input the resolver used: the license file, the cached cloud plan, the enforce variable, and the in-process cache. Usually it is a license that did not activate, a stale plan cache, or a changed machine fingerprint.

A control does nothing#

Check what the Guard tab says next to the button. A control that cannot work says why:

• OpenClaw pause is advisory without the proxy running. `clawmetry proxy

start`.

• A Cursor editor session is not a separate process and cannot be signalled.
• A Windows stop reaches the whole console, not one process.

→ Pause, stop, kill

clawmetry update reports a strange version#

If your working directory contains a dashboard.py — a ClawMetry checkout — it shadows the installed package and the version comparison is against the wrong thing. Run it from anywhere else.

Still stuck#

clawmetry status --json    > /tmp/cm-status.json
clawmetry runtimes --json  > /tmp/cm-runtimes.json
clawmetry diagnose --json  > /tmp/cm-diagnose.json
DEBUG=1 clawmetry sync --foreground 2>&1 | head -100 > /tmp/cm-sync.log

Open an issue with those. Check them for secrets first — the sync log can name paths, and status includes your node id.