Incidents

How DebugBundle groups events into incidents using fingerprinting and lifecycle management.

An incident represents a unique problem detected in your application. DebugBundle automatically groups related events into incidents using fingerprinting, tracks their lifecycle, and generates debug bundles for investigation.

Event-to-Incident Pipeline

Events → Normalize → Fingerprint → Group → Incident → Bundle

Ingest — SDKs send events to POST /v1/events. Events are persisted to object storage and queued for processing.
Normalize — The worker normalizes event data (strips dynamic values like UUIDs, timestamps, IP addresses, email addresses).
Fingerprint — A deterministic fingerprint is computed from the normalized message, error type, route template, top stack frames, HTTP method, and HTTP status.
Group — Events with the same fingerprint are grouped into a single incident.
Bundle — Debug bundles are generated at occurrence thresholds (1, 3, 10 events).

Fingerprinting

The fingerprint is a SHA-256 hash computed from these fields (when available):

Field	Description
`environment`	Deployment environment (always included).
`normalized_message`	Error message with dynamic values stripped.
`error_type`	Exception class name (e.g., `TypeError`, `NullPointerException`).
`route_template`	URL route template (e.g., `/api/users/:id`).
`top_frames`	Top application stack frames (excluding library/framework frames).
`http_method`	HTTP method (GET, POST, etc.).
`http_status`	HTTP response status code.

The matched_fields array on each incident records which fields contributed to its fingerprint, providing transparency into grouping decisions.

Normalization Patterns

Before fingerprinting, dynamic values are stripped from messages:

Pattern	Replacement
UUIDs	`[UUID]`
Email addresses	`[EMAIL]`
ISO timestamps	`[TIMESTAMP]`
IPv4 addresses	`[IP]`
Hex values	`[HEX]`

This ensures that occurrences of the same underlying error are grouped together regardless of dynamic payload content.

Event Types

Events are classified into three categories:

Event Class	Event Types	Role
Incident Signal	`backend_exception`, `frontend_exception`, qualifying `log_event`, preset-specific immediate `request_event` failures (`minimal`: 5xx; `balanced`: 5xx plus 408/423/424/425/429; `investigative`: balanced plus 409), plus any project-selected `4xx` statuses from `immediate_client_error_statuses`	Create/update incidents directly.
Context Signal	`request_event` outside the preset's immediate failure set, `frontend_breadcrumb`, `deploy_metadata`, `probe_event`, lower-level `log_event`	Enrich existing incidents with additional data. Repeated contextual request failures can open request-anomaly incidents without changing the stored event class.
Operational Signal	`error_suppressed`	Tracked but may not create new incidents.

Incident Lifecycle

Created

A new incident is created when an incident signal does not match an existing fingerprint.

Open

Matching events continue to update occurrence counts, context, bundles, and alerts.

Resolved

A team member or agent explicitly marks the incident resolved.

Reopened

A new matching event after resolution reopens the incident as a regression.

State	Description
Open	Active incident, events still arriving. Default state.
Resolved	Incident marked resolved by a team member.
Reopened	A resolved incident that received new matching events (regression).

Resolution

Incidents can be resolved via API, CLI, or MCP:

# CLI
debugbundle resolve inc_01H...
debugbundle resolve inc_01H... inc_01J...

# API
curl -X POST https://api.debugbundle.com/v1/incidents/inc_01H.../resolve \
  -H "Authorization: Bearer dbundle_mem_a1b2c3d4..."
curl -X POST https://api.debugbundle.com/v1/incidents/resolve \
  -H "Authorization: Bearer dbundle_mem_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{"incident_ids":["inc_01H...","inc_01J..."]}'

# MCP
resolve_incident(incidentId: "inc_01H...")
resolve_incidents(incidentIds: ["inc_01H...", "inc_01J..."])

When an incident is resolved, a bundle.resolved webhook event is fired.

Regression

If new events arrive matching a resolved incident's fingerprint, the incident is automatically reopened and a bundle.reopened webhook event is fired. If the regression correlates with a recent deploy, the regression_after_deploy flag is set and deploy metadata is included in the webhook payload.

Severity

Level	Meaning	Auto-Assigned For
`low`	Minor, informational.	Most event types (default).
`medium`	Moderate impact.	`error_suppressed` events and opaque browser-native `resource_error` captures.
`high`	Significant, needs attention.	`backend_exception`, non-opaque `frontend_exception`, immediate request-failure incident signals.
`critical`	Severe, immediate action required.	Manually escalated.

Severity is automatically inferred from event type and signal confidence at grouping time. Opaque browser-native window_error captures infer low because browsers did not expose enough application detail to justify paging-level severity by default. Severity can be manually escalated but not downgraded.

Sources

Incidents can come from two sources:

Source	Description
Local	Generated by `debugbundle process` on local log files.
Cloud	Generated from events ingested via `POST /v1/events`.

Use --source filters to view incidents from a specific source:

debugbundle incidents
debugbundle incidents --source cloud
debugbundle incidents --source local

Next Steps

Reproduction — Reproduction artifacts
Bundles — Debug bundle structure
API Incidents — Incident API endpoints

Incidents

Created

Open

Resolved

Reopened

On this page