Troubleshooting

Troubleshooting

First step: turn on the self-log

export TICKETMAN_DIAG_DEBUG=true

The SDK writes its internal decisions and errors to stderr and Trace: invalid configuration, spool problems, delivery failures and retries, rate-limit hits, masking timeouts. The SDK never logs anything otherwise.

No reports arrive

1. Endpoint configured? Without TICKETMAN_DIAG_ENDPOINT the SDK is inert by design. The self-log prints No endpoint configured: SDK inactive.
2. Scheme valid? Only absolute http(s) URLs are accepted; anything else disables the SDK.
3. 401 or 403 in the self-log? The API key is wrong or revoked. Such reports are dropped and never retried.
4. Reports piling up in the spool? Delivery is failing. The self-log shows the reason and the backoff. Check that the app can reach the endpoint.
5. Server kill switch? A pauseUntil throttle hint stops sending until the given time (self-log: Server paused sending until …).

Crash reports specifically

• Crash reports are spooled, not sent, at crash time; one bounded 3-second send attempt is made. They are delivered when the app next starts. If the app never restarts, the .tmdiag file is in TICKETMAN_DIAG_SPOOL_DIR.
• The spool directory must be writable by the app's user.
• In containers, the default spool lives under /tmp and dies with the container. Point TICKETMAN_DIAG_SPOOL_DIR at a mounted volume if crash reports must survive pod restarts.

Minidumps

• If TICKETMAN_DIAG_ENABLE_DUMPS=true and the dump exceeds TICKETMAN_DIAG_MAX_ATTACHMENT_SIZE_MB, it is discarded (noted in the self-log).
• Linux containers need ptrace: add the SYS_PTRACE capability (Kubernetes: securityContext.capabilities.add: ["SYS_PTRACE"]). Otherwise dump creation fails, though the report is still delivered without it.

HTTP errors not captured

• ASP.NET Core: app.UseTicketManDiagnostics() must run before anything that swallows exceptions, such as UseExceptionHandler, or the middleware never sees them.
• Express: mount ticketmanRequestHook() before your routes and ticketmanErrorHandler() after them (but before your own error middleware — the handler always forwards with next(err)).
• Status-only errors are captured per TICKETMAN_DIAG_HTTP_STATUS_RANGES (default 500-599). A 404 is not captured unless you add 400-499 or 404.

Too many or too few reports

• The client-side rate limit is per fingerprint: TICKETMAN_DIAG_RATE_LIMIT (default 10/5m). Suppressed occurrences are counted in the next report's suppressedCount.
• The server can also set a sampleRate throttle hint. Crash reports are never sampled out.

Desktop app missing UI exceptions

See Desktop integration. Init() must run on the UI thread.