Troubleshooting

SDK Not Capturing Events

Events not appearing in .debugbundle/local/events/

1. Check enabled is not false:

   DebugBundle.init({
     projectToken: 'local',
     enabled: true,  // Default, but verify it's not overridden
   });

2. Check the project token: Use 'local' for local-only mode or a valid dbundle_proj_* token for connected mode.

3. Check the projectMode: In local-only mode, events write to disk on the current machine. In connected mode with development, events also write to disk. In connected mode with staging or production, events send to the API instead of relying on local disk.

4. Flush on exit: The SDK flushes on process shutdown, but if your process is killed with SIGKILL, buffered events are lost. Call DebugBundle.flush() if you need to force a flush.

5. Check sampleRate: A value of 0 drops all events.

Events not showing in the cloud

1. Verify the project token: Run debugbundle verify cloud --project-id proj_xxx.
2. Prove ingestion with a synthetic incident: Run debugbundle verify cloud --project-id proj_xxx --trigger-5xx, or debugbundle verify cloud --project-id proj_xxx --trigger-4xx 403 when the capture policy promotes that client-error status.
3. Check the endpoint: Ensure endpoint in SDK config points to the correct API URL.
4. Check rate limits: The API returns rate_limited errors in the response. Check your tier's limit.
5. Check network: Ensure your environment can reach api.debugbundle.com (or your self-hosted endpoint). In Kubernetes or other locked-down environments, verify outbound HTTPS egress rules, firewall allowlists, and any required proxy configuration.

CLI Issues

debugbundle setup fails

1. Run from project root: Setup needs to find package.json or a recognized project structure.
2. Check permissions: Setup creates directories and writes files. Ensure write access to the project directory.
3. Re-run with --non-interactive: If the interactive prompts hang (e.g., in CI), use debugbundle setup --non-interactive.

debugbundle process — "No events to process"

Events must exist in .debugbundle/local/events/. Verify:

ls .debugbundle/local/events/

If empty, your SDK or log ingestion hasn't written events yet. On a server-local workflow, verify you are checking the same server or mounted volume where the application writes .debugbundle/local/events/. See Local Workflow for capture steps.

debugbundle doctor shows warnings

Authentication errors (exit code 2)

1. Check auth file exists: ls ~/.debugbundle/auth.json
2. Re-login: debugbundle login
3. Verify token is valid: debugbundle whoami
4. Check token type: Cloud commands require a member token (dbundle_mem_*), not a project token.

Cleaning up intentional smoke incidents

Treat active incidents as actionable work. Active means open or regressed. After a fix is verified, or after an intentional smoke, dogfood, or verification incident has served its purpose, resolve it.

1. Review the needs-attention queue: debugbundle incidents --status active --json
2. Resolve the intentional incidents: debugbundle resolve <incident-id> [incident-id ...]
3. Re-check the queue: debugbundle incidents --status active --json

If you use jq, you can batch-resolve common synthetic titles:

debugbundle incidents --status active --json \
  | jq -r '.incidents[] | select(.title | test("smoke test|dogfood|verification|synthetic"; "i")) | .incident_id' \
  | xargs debugbundle resolve

Webhook Delivery Failures

Deliveries stuck in retrying

1. Check your endpoint is reachable: DebugBundle sends POST requests to your URL. Ensure it returns 2xx.
2. Check response time: If your endpoint is too slow, deliveries may time out.
3. Verify the URL: debugbundle webhook list --project-id proj_xxx to confirm the URL is correct.

Signature verification fails

1. Use the raw request body: Parse the HMAC from the raw string body, not the parsed JSON. Middleware that modifies the body (e.g., body parsers) can break verification.
2. Use timing-safe comparison: Always use crypto.timingSafeEqual() (Node.js) or hmac.compare_digest() (Python).
3. Check the signing secret: The secret is shown once at webhook creation. If lost, delete and recreate the webhook.

Webhook auto-disabled

After repeated delivery failures, webhooks are automatically disabled. To re-enable:

debugbundle webhook update whk_xxx --project-id proj_xxx --is-enabled true

Fix the underlying delivery issue first, then re-enable.

Browser SDK Issues

Events not captured

1. Check enabled: Verify it's not disabled.
2. Check sessionSampleRate: A value of 0 drops all sessions.
3. Check ad blockers: Ad blockers may block requests to api.debugbundle.com. Use the relay transport to route through your own backend.
4. Check CSP headers: If your Content Security Policy blocks the DebugBundle endpoint, add it to connect-src. This applies to browser delivery only, not to Node.js, Python, PHP, or .NET server SDKs.

Bundle points at debugbundle-browser-sdk.js

If a frontend bundle shows Window error or Browser resource load error with the first frame inside debugbundle-browser-sdk.js, the SDK usually observed an opaque browser-level error rather than causing the failure. The browser did not provide a usable application stack, so DebugBundle records the global hook metadata in payload.browser_event.

Check these fields first:

1. browser_event.kind: resource_error points to a failed script, stylesheet, image, or similar browser resource. window_error means a global error event reached the SDK without a normal Error object.
2. browser_event.target.source_url: The best clue for resource-load failures.
3. browser_event.file_name, line_number, column_number: The browser's source-location fields when available.

To improve future captures, initialize the Browser SDK before app code, add framework-level captureException(error) calls for error boundaries, publish source maps, and configure CORS plus crossorigin="anonymous" for cross-origin scripts.

Relay not working

1. Verify the relay handler is registered: Check your Express/Fastify/Next.js route handles POST to /debugbundle/browser (or your configured relay path).
2. Check CORS: The relay should be same-origin, so CORS shouldn't apply. If using a different origin, configure CORS.
3. Check the relay spool: Run debugbundle doctor --check-relay to check for stuck spool files.
4. Check relay storage in containers: If you rely on durable relay writes, mount spoolDir on persistent storage. Otherwise, spool files disappear when the pod or container is replaced.

Self-Hosted Issues

Containers fail to start

1. Check Docker is running: docker info
2. Check port conflicts: The API, Postgres, Redis, and LocalStack all bind to ports. Ensure no conflicts.
3. Bootstrap S3: The API requires the debugbundle-raw-events bucket. Run make s3-bootstrap or make infra-bootstrap before starting.

API returns 500 errors

1. Check Postgres is healthy: docker compose ps — Postgres should show "healthy".
2. Check Redis is running: Redis is required for rate limiting and sessions.
3. Check container logs: docker compose logs api for error details.

Getting Help

If you're stuck:

1. Run debugbundle doctor --json and review the full diagnostic output
2. Check the FAQ for common questions
3. Open an issue on GitHub with the doctor output and reproduction steps