Troubleshooting

Start with the symptom below. Keep diagnostics visible while investigating: pass --verbose instead of --quiet, and inspect stderr if you redirect report data.

Empty report or missing source

Check discovery before changing paths:

llm-usage doctor
llm-usage doctor --source codex,claude

Doctor lists the paths each source searched and marks it found, not installed, unparseable (files without readable usage), or failed, plus ledger health. It does not load pricing. A found source can still produce no matching events: date, model, provider, and configured source filters may exclude them.

Run a scoped report without date, provider, or model flags:

llm-usage daily --source codex

Check llm-usage config show for persistent defaults. If discovery cannot find your data, compare the reported path with the source’s default locations and pass an explicit override:

# Directory-backed source
llm-usage doctor --source codex --codex-dir /path/to/.codex/sessions

# Database-backed source
llm-usage doctor --source opencode --opencode-db /path/to/opencode.db
llm-usage doctor --source goose --goose-db /path/to/goose/sessions.db

Some tools require extra setup before they record usage. For example, Copilot CLI needs its telemetry export configured. Read the source guide before assuming existing conversations contain token data.

Runtime or path override errors

The CLI requires Node.js 22.16+ or 24+ (Node 23 lacks the SQLite busy timeout the ledger uses), including built-in node:sqlite for its ledger and SQLite-backed sources. Check the runtime used by your shell:

node --version

Directory-backed sources accept named flags or repeatable --source-dir entries. OpenCode and Goose require their database flags instead:

llm-usage monthly \
  --source-dir codex=/path/to/.codex/sessions \
  --source-dir claude=/path/to/.claude/projects

llm-usage monthly --opencode-db /path/to/opencode.db
llm-usage monthly --goose-db /path/to/goose/sessions.db

Use the actual sessions directory or database file, not its parent. Explicit directory overrides must exist. Repeat a directory flag or --source-dir entry to scan several directories for one source; OpenCode and Goose take one database each. Paths containing spaces need shell quotes. The CLI reference lists every supported flag.

Missing or partial cost

A dash (-) means no contributing event has a resolved cost. A tilde (~$4.82) means only part of the row was priced. Token totals still include unpriced events.

The stderr line starting with ~ marks costs lists the models without a price. Check the model names and pricing diagnostics. If a model is not in LiteLLM, supply per-model pricing overrides. Do not assume a different model’s rates apply.

Default LiteLLM pricing can fall back to the bundled snapshot even without a warm cache. Its diagnostic includes the snapshot date. Run online to refresh pricing:

llm-usage monthly

If pricing.offline = true is saved in your config, see Configuration for how to run with online pricing. Custom pricing URLs use their own matching cache and do not fall back to the bundled default snapshot.

A pricing load error can also come from an invalid overrides file or an unreachable custom URL. Keep the original error message when reporting the problem.

Unexpected totals or missing older history

Source tools normalize token buckets differently. Check the relevant source guide before comparing the report with the tool’s own dashboard. Also check the report timezone and date bounds.

Reports include retained events from files that left the disk by default. To compare against discovered files only, use:

llm-usage monthly --no-history

The ledger contains retained history

Deleting events.db deletes history retained for departed files. Before resetting it, read Caching and history. A fresh ledger can reparse existing files, but it cannot restore files that have disappeared.

Wide tables or broken redirected output

Switch to JSON or Markdown when a terminal table does not fit. Keep report data and diagnostics in separate files:

llm-usage daily --json > usage.json 2> usage.log

Report JSON uses a versioned envelope. If a script expects the pre-0.8 shape, follow Upgrading to 0.8, and see Upgrading for later changes. events uses --format jsonl or --format csv, rather than --json.

Report a reproducible issue

Include your CLI version, Node.js version, source, exact command, and diagnostics. Use a fixed timezone and date range when reporting total differences:

llm-usage --version
node --version
llm-usage monthly --source codex --timezone UTC \
  --since 2026-09-01 --until 2026-09-30

Review logs and fixtures before attaching them: they can contain paths, repository names, or session content. Open an issue on GitHub.