Skip to main content
Early pricing is live. Start free for up to 3 AI systems — no card, no time limit.Early pricing is live. Free for up to 3 AI systems.
All docs
How-to guide

Troubleshoot the collector

What each collector message means and what to do about it, on macOS, Windows and Linux.

10 minFor: Engineer

Every message the collector prints is listed here with what it means. The collector only ever reads local logs and sends token counts; nothing here involves conversation content.

"nothing new to push"

Not an error. Every day-key in the window was already pushed with the same figures, so there is nothing to send. The state file still saved its file cache. If you expected new usage, run scan --since 7 to see what was counted.

Authentication errors

You seeMeaning and fix
error: config has no ingest_key, no token, and no email/passwordThe config file is missing or has no credential. Check the path under Where the files are, or paste the installer again to rewrite it. Exit code 2.
404 on pushThe key is malformed, revoked, or belongs to a deleted source. The 404 is deliberate: an unauthenticated caller learns nothing. Revoke the source on Connections and connect again; the new key goes in config.toml.
403, naming another receiverThe key is valid but belongs to another connection kind. A Developer machines key only opens /usage/gateway/collector/events. Use the key the Developer machines door issued.
422 with a field nameA record failed validation. The collector clamps every enum before sending, so this points at a typed [mapping] value; see Usage is unattributed.

Note

Credential precedence is fixed: an ingest_key wins over a --token, which wins over token in the file, which wins over email and password. The one-command installer writes only an ingest_key.

"(no usage found in window)"

scan found no Claude Code or Hermes session in the last N days on this machine. Widen the window (scan --since 30), or check the collector is looking in the right place: it reads ~/.claude/projects and ~/.hermes/state.db under your home directory. A different home, or logs kept elsewhere, needs the environment variables under Paths.

Usage is unattributed

The collector names each project by its directory's basename, lowercased, with anything outside a-z0-9_- replaced by a hyphen. A fingerprint the workspace does not know as an AI system is resolved through the source's harness mapping, then the source's default system, and otherwise lands in the unattributed pool with its fingerprint, host and user kept, so someone can assign it later. It is a coverage gap shown honestly, not zero usage. Two fixes:

  • In config.toml, map a directory to the system's fingerprint. A typed value must match ^[a-z][a-z0-9_-]{0,63}$; the collector refuses the file otherwise, before anything is sent.
  • On Connections, set the source's default system, or assign the pooled usage to a system there.
config.toml
[mapping]
"/Users/ana/work/invoice-bot" = "invoice-bot"
"/Users/ana/work/support-triage" = "support-triage"

Caution

A machine door never registers a system from a directory name. That rule exists because one push once minted 36 junk systems from worktree names. Register the system first, then map to it.

Where the files are

FilePath
Command~/.oabo-collector/venv/bin/oabo-collector
Config~/.config/oabo-collector/config.toml
State~/.local/state/oabo-collector/state.json
Claude Code logs (read only)~/.claude/projects
Hermes state (read only)~/.hermes/state.db

Reinstall

Paste the installer command from Connections again. It repairs a half-built environment rather than reporting it, rewrites the config, and pushes once. If you also want a clean re-push, delete state.json first; a full re-push is safe because the server replaces a day's rows rather than adding to them.

Caution

The state file is not namespaced by server. If you ever pointed the same machine at a different Oabo address, delete state.json before pushing to the real one, or the earlier push markers will suppress records.

Previous

Run the collector on a schedule

Last documented 2026-11-18 against master fb17e1c5. Live release 0.3.1.