Troubleshooting

No events appear after npx @tracemason/cli init

Run npx @tracemason/cli status. It checks, in order:

  • hooks — are Tracemason's hooks present in a Claude Code settings file? Sessions started before init do not pick up new hooks; start a new one.
  • queue — a growing number means events are being captured but not delivered.
  • last error — the most recent delivery or hook error.
  • connectivity — whether the server accepts the key right now.

Then npx @tracemason/cli test to send one event, and npx @tracemason/cli flush to push the queue.

"ingestion key rejected (401)"

The key was revoked or the organization was deleted. Run npx @tracemason/cli init again.

"Refusing to use http://…"

Collectors and SDKs only talk to HTTPS endpoints, apart from localhost. This only appears when --endpoint or TRACEMASON_ENDPOINT names a plain http address: remove it to use the hosted service, or put your self-hosted server behind TLS.

Events are being dropped

npx @tracemason/cli status shows a dropped count and the dashboard marks the collector degraded. This happens when the server was unreachable long enough for the local queue (5,000 events / 8 MB) to fill, or a batch was refused outright. Check connectivity and the monthly quota (Settings → Billing).

quota_exceeded (HTTP 429)

The organization reached its monthly event allowance. Rejected events are counted under Settings → Billing. Upgrade the plan or wait for the next calendar month (UTC).

A session shows as "stale"

It stopped sending events without a session.ended — typically a closed terminal or lost network. Later events from the same session reopen it.

A command is marked "opaque"

The classifier could not fully analyse it (see Security policies). The category shown is a best effort.

A commit is not linked to my session

  • Is the repository connected through the GitHub integration and tracked?
  • Is the organization on a plan with Git correlation (Team and above)?
  • Verified needs the collector to have seen the commit being created inside a tool call. A commit made by hand in another terminal will be Correlated or Possible at best.
  • To link explicitly, add Tracemason-Session: <session id> to the commit message or PR description.

The realtime indicator says "reconnecting"

The browser's event stream dropped. It reconnects on its own and replays what it missed.

Email invitations or alerts do not arrive

The invitation link is always shown to the inviter, so it can be shared directly. Check the spam folder for alerts.

The 3D topology is blank

WebGL is unavailable. The page falls back to the Operations tables automatically; you can also switch to them manually.

Self-hosted servers

The rest of this page applies only if you run Tracemason yourself.

GitHub webhooks return 401

The signature did not verify. Check that GITHUB_WEBHOOK_SECRET on the API matches the App's webhook secret exactly, and that no proxy rewrites the request body.

The realtime indicator never connects

Check that your reverse proxy does not buffer text/event-stream responses.

Email is not sent

Without SMTP_URL configured, Tracemason writes the message to the API log and reports the delivery as skipped.

Running the tests

docker compose up -d
pnpm build
pnpm test                 # unit + API integration tests
pnpm test:e2e             # Playwright; needs `pnpm dev` running
cd packages/sdk-python && python3 -m unittest discover -s tests