FAQ

General

What is DebugBundle?

DebugBundle is a debugging platform that captures exceptions, logs, HTTP context, and diagnostic data from your applications, processes them into structured debug bundles, and provides reproduction artifacts. It works without a cloud account wherever you can run the SDK and CLI against local files, and optionally connects to a hosted service for team collaboration.

How is DebugBundle different from error tracking tools like Sentry?

DebugBundle focuses on actionable debugging context, not just error alerts. Every incident includes a full debug bundle with reproduction commands (curl, httpie), probe data, breadcrumbs, and request/response context. It's also local-first: you get the core workflow without creating an account or sending data to DebugBundle Cloud.

Do I need a cloud account to use DebugBundle?

No. DebugBundle is fully functional in local-only mode. Run debugbundle setup, capture events with the SDK, run debugbundle process, and inspect incidents on the machine or storage volume where those files live. A cloud account adds team collaboration, hosted retention, and centralized ingestion from production environments.

SDKs

Which languages are supported?

Does the SDK affect my application's performance?

No. The SDK is designed to be invisible:

• Capture is asynchronous and non-blocking
• Events are batched and flushed on a timer (not per-event)
• Storm suppression prevents runaway event volume
• The SDK never throws exceptions into your code
• If the SDK fails internally, it silently swallows the error

Can I use DebugBundle with Express, Fastify, or Next.js?

Yes. The Node.js SDK includes first-class integrations for all three:

app.use(DebugBundle.express());                     // Express
app.register(DebugBundle.fastify());                // Fastify
export default DebugBundle.nextjs(handler);          // Next.js

Does the SDK support my logger (pino, winston, bunyan)?

Yes. The Node.js SDK auto-detects and attaches to pino, winston, and bunyan. You can also pass a logger instance explicitly. See Node.js SDK — Logger Integrations.

Can I manually trigger an incident from a catch block?

Yes. The normal way is to call captureException() or captureError() inside the catch block. Those exception events are incident-driving, so they create or update an incident in the usual pipeline.

If you want a notification, make sure you also have an alert rule or webhook configured for new incidents. A manual capture creates the incident signal; alerts and webhooks handle the delivery.

captureLog() and captureMessage() can also contribute, but only incident-level log severities such as error, fatal, or critical create incidents. For explicit catch-block reporting, captureException() is the clearest path.

Data & Privacy

What data does the SDK capture?

The SDK captures:

• Exceptions (type, message, stack trace)
• Logs (level, message, structured data)
• HTTP requests and responses (method, URL, status, headers, body)
• Breadcrumbs (clicks, route changes, network calls, mobile screen/app lifecycle)
• Device context (browser OS/viewport and Android, iOS, or React Native app/device/runtime facts)
• Probe data (custom diagnostic ring buffers)

Is sensitive data redacted?

Yes. By default, the SDK redacts values for fields named: password, secret, token, authorization, cookie, ssn, credit_card. Redaction happens in the SDK before data leaves the process. You can add custom field names to the redaction list.

Where is my data stored?

Can I self-host DebugBundle?

Yes. DebugBundle ships a Docker Compose stack that runs all components (API, Worker, Postgres, Redis, S3-compatible storage) on your infrastructure. Your data never touches third-party services. See Installation for deployment instructions.

Why am I not receiving errors in DebugBundle?

The most common causes are configuration and delivery rules rather than the SDK crashing or containers breaking.

• In connected staging and production, backend SDKs send events over HTTP. They need outbound network access to your configured DebugBundle API endpoint. In locked-down environments, check firewall rules, proxy configuration, NAT/VPC egress, or similar outbound controls.
• Browser delivery can be blocked by browser-side policy. If the Browser SDK sends directly to DebugBundle cloud, your CSP must allow the endpoint in connect-src. If you use a same-origin relay, CSP usually only needs to allow your own origin instead.
• Your project's Capture Policy may intentionally filter or downgrade what gets shipped. For example, some client-error request statuses only become incident-driving events when the policy promotes them.
• In local-only mode, and in connected development, events are written to local disk. If you run inside ephemeral containers or pods and do not mount persistent storage, those local event files disappear when the container is replaced.
• Buffered events still need time to flush. Graceful shutdown is supported, but a hard kill such as SIGKILL can still drop in-memory events.

If you are unsure which case applies, start with Troubleshooting and then verify the project's Capture Policy.

Does a browser bundle pointing at debugbundle-browser-sdk.js mean the SDK broke my app?

Not usually. For opaque browser window errors, the SDK may need to synthesize a fallback error such as Window error or Browser resource load error because the browser did not expose the original JavaScript Error object. The stack can then point at the SDK listener that captured the event, even though the underlying failure came from the page, a resource load, or a cross-origin script.

Inspect payload.browser_event on the frontend_exception event. target.source_url, file_name, line_number, and column_number are the best available browser clues. If opaque is true, improve setup fidelity by loading the SDK early, capturing framework error-boundary exceptions explicitly, serving source maps, and configuring CORS plus crossorigin="anonymous" for cross-origin scripts.

CLI

How do I install the CLI?

npm install -g @debugbundle/cli

What does debugbundle setup create?

It generates the local scaffold including:

• .debugbundle/profile.json — Project profile
• .debugbundle/local/connection.json — Connection mode config
• .agents/skills/debugbundle/ — AI agent skill and references
• Directory structure for events, bundles, and reproductions

See Setup & Configuration for the full scaffold layout.

Can I use the CLI in CI/CD pipelines?

Yes. All commands support --json output for machine parsing. Use --non-interactive for setup and --auth-file to point to a custom auth file location.

Webhooks

Which events can I subscribe to?

bundle.created, bundle.updated, bundle.resolved, bundle.reopened, improvement_bundle.created, incident.spike_detected, verification.passed, verification.failed.

How do I verify webhook signatures?

Every delivery includes an X-DebugBundle-Signature header containing an HMAC-SHA256 hex digest. Verify it using the signing secret provided at webhook creation. See Webhooks — Signature Verification for code examples.

What happens if my endpoint is down?

Deliveries retry with exponential backoff. After sustained failures, the webhook is automatically disabled. You can re-enable it and retry individual deliveries. See Webhooks — Delivery Lifecycle.

Pricing & Billing

Is there a free tier?

Yes. The free tier includes unlimited projects, get-started capacity, and the core debugging workflow. Paid-only features such as GitHub automation or Slack integration require Solo or Team. Eligible organizations can also start a 30-day no-card Solo or Team trial before converting to paid.

What happens when I exceed the rate limit?

Events beyond the rate limit are rejected with rate_limited in the ingestion response. The SDK handles backoff automatically. No data corruption occurs — events are simply dropped at the boundary.

What is a capacity unit?

Capacity unit is the billing unit for hosted allowance on paid plans. These units expand your shared hosted allowance; they do not cap how many projects you can create.

MCP (Model Context Protocol)

What is MCP?

MCP is a protocol for AI agents to interact with tools. DebugBundle exposes its full capabilities as MCP tools, allowing AI agents in IDEs (Cursor, VS Code Copilot, etc.) to investigate incidents, retrieve bundles, manage webhooks, and run diagnostics.

How do I set up MCP?

The MCP server reuses your CLI auth state by default. After running debugbundle login, configure your IDE's MCP settings to point to the DebugBundle MCP server. Headless or marketplace-managed clients can set DEBUGBUNDLE_MEMBER_TOKEN in the MCP server environment instead. See the MCP documentation for details.