Troubleshooting Guide

The redacted application log is the first stop: %LOCALAPPDATA%\ClaudeOrgUsageMonitor\logs\claude_monitor.log (raise verbosity via Settings → Data & Backup → Logging level → DEBUG).

Connection & keys

“We're on the Team plan and there is no Analytics API key to create.” Correct — that key does not exist on the Team plan (the Analytics API is Enterprise-only per the official Anthropic documentation, and the Admin / Claude Code Analytics APIs belong to Claude Console organizations). This is Anthropic's plan design, not a fault. Set Settings → API Connections → Organization plan to Claude Team plan and import the official exports instead: the Claude Code analytics export (claude.ai/analytics/claude-code → Export all users) and the spend report from your analytics settings, via Sync & Audit → Official export imports. See the API Key Setup guide.

Symptom	Cause & fix
Authentication failed (401) on Test connection	Key mistyped/revoked, or the wrong key type for the endpoint (Analytics vs Admin keys are not interchangeable). Re-create the key in the right console and paste it again — see API_KEY_SETUP.md.
Permission denied (403)	The key is valid but the plan/scope doesn't include that endpoint (e.g. Claude Code Analytics on a workspace-scoped key). Use an org-level Admin key / Analytics key with read:analytics.
Endpoint not available (404) on some categories	Normal: that data category isn't offered on your plan. It is labeled Unavailable, excluded from scoring, and can be covered by official CSV imports.
Rate limit exceeded (429) persists	The Enterprise Analytics API allows 60 req/min org-wide, shared with any other tooling. The client already throttles and honors Retry-After — schedule syncs when other consumers are idle, or ask Anthropic to raise the limit.
Network failure / timeout	Check proxy/firewall allows api.anthropic.com:443. TLS interception with a private CA will fail verification — install the CA into the Windows trust store; never disable TLS verification.
No API key configured when pressing Sync	Add a key in Settings → API Connections (demo mode intentionally has no sync).

Data looks wrong

Symptom	Cause & fix
Yesterday/today missing	Official data lags (~1 day engagement, ≤24 h usage/cost). The sync stops cleanly at the newest aggregated day and the freshness date shows how far data goes.
Numbers changed since last week	Anthropic revises recent days; the lookback re-fetch (default 7 days) picks revisions up. For invoice-grade cost, prefer periods ≥30 days old.
User shows No Data but should have usage	Check Settings → API Connections: is the category serving that product Available? If it's plan-limited, import the official export for it. No Data means "no reliable source", never zero.
Everyone at 0% after enabling a new metric	The metric's product has no available source for the period, or targets are unrealistic. Check the user drill-down: each metric row shows applicable/why-not, effective target and actual.
Chat totals differ from the claude.ai dashboard	Compare identical UTC date ranges and remember distinct counts are approximations (<2% typical). The report footer records data source and freshness for audit.
Import shows "skipped (API data)"	Working as designed: official API data outranks file imports for the same user/day/metric, so re-importing can't corrupt synced data.
Seat count says "derived from active members"	Your sources don't report assigned_seat_count; the app derives seats from active directory members and labels the source.

Alerts

Symptom	Cause & fix
Expected alert missing	Check: alerts enabled? user exempt (see the Exemption column / reason)? inside the new-user grace period? suppression window (default 7 days) still active? already recorded for this period? The evaluation tab shows the exact reason per user.
Alert for someone on leave	Add an exemption (exact email) with an expiration date — it auto-returns to evaluation afterwards.
No Windows toast notifications	Windows Focus Assist / notification settings can suppress tray balloons; the in-app Alerts page always shows everything regardless.
Email test fails	SMTP: verify host/port/security mode and that the password was saved (Credential Manager). Graph: tenant/client IDs, client secret saved, Mail.Send application permission with admin consent, and a real sender mailbox. The error dialog carries the exact reason (redacted).

Sync & database

Symptom	Cause & fix
Sync says partial	Some categories succeeded, others failed — open the run (double-click in Sync history) for per-category reasons. Successful categories kept their data; retry after fixing the cause.
Sync appears stuck	Large initial syncs are throttled (~1.1 s/request on the Analytics key). Progress shows the current category; Cancel stops cleanly after the current request and keeps everything already ingested.
a synchronization is already running	One sync at a time (including scheduled ones). Wait or cancel the running one.
Database locked / corrupt after a crash	WAL mode makes this rare. Run Settings → Data & Backup → Back up database now; if the app won't start, restore the latest backup (the previous DB is kept as *.pre_restore).
Restore refuses a file	Restores validate SQLite header + integrity and, for .enc backups, require the same Windows user/machine credential-store key. Use a plain backup from the same install, or the documented BitLocker path for machine moves.

UI & installation

Symptom	Cause & fix
App does not start at all	Re-download and reinstall from the Download page (a partial download is the usual cause — check the SHA-256). If it still fails, send %LOCALAPPDATA%\ClaudeOrgUsageMonitor\logs\claude_monitor.log to your IT administrator.
Blank/garbled window over RDP	Force software rendering: set environment variable QT_OPENGL=software before launching.
SmartScreen warning on the installer	The installer is unsigned by default. Verify the file hash you built, then "More info → Run anyway", or sign it with your org certificate.
High-DPI text too small/large	Windows display scaling is honored by Qt; per-monitor overrides: right-click the exe → Properties → Compatibility → High DPI settings.
Keyring errors on locked-down machines	If the Credential Manager is disabled by policy, the app falls back to a labeled reduced-security store; prefer enabling the Credential Manager service.

Demo mode

Demo mode uses a separate data directory (…\ClaudeOrgUsageMonitor\demo) and an in-memory secret store; it never contacts the network and Sync is disabled by design. Delete the demo folder to regenerate fresh demo data.

Still stuck?

Collect: the log file, the sync run detail (Sync & Audit), and the capability table (Settings → API Connections) — these three answer most questions without exposing any secrets.