bug_handler

Use when reviewing code in an app that depends on bug_handler - PR review, "check our error handling", pre-release audits, or "are we using bug_handler correctly". Finds violations of the guard contract: string errors in state, unreported catches, raw exceptions crossing repository boundaries, missing source labels, misused isReportable.

Use when bug_handler reports are missing, duplicated, delayed, or unexpected - "nothing arrives in Sentry", "capture doesn't send", "errors only show sometimes", outbox files piling up in bug_report_outbox, StateError about initialization, or events arriving that should have been suppressed.

Use when connecting bug_handler to a delivery backend or enriching its reports - writing a custom Reporter (Sentry, Crashlytics, Slack, first-party HTTP endpoint), a custom ContextProvider (feature/session/cart context), or an EventTransform. Also use when someone tries to use the shipped Sentry/Crashlytics "adapters" (they are empty placeholder files).

Use when writing or refactoring feature code in an app that depends on bug_handler - repositories/services that can fail, cubits/blocs/notifiers/controllers that load data, error states, try/catch blocks, or "handle errors properly" requests. Also use when choosing which exception type to throw or how errors should reach the UI.

Use when a project depends on bug_handler 0.0.1-dev.x or contains its legacy API - BugReporter, ErrorHandler, handleError, wrapper, ReportResult, ReportConfig, sentryDsn, ManualReporter, SentryReporter, ErrorDisplayWidget, or imports like package:bug_handler/core/error_handler.dart - and needs to move to the current 1.0.0-dev.x API.

Use when adding the bug_handler package to a Flutter app for the first time, wiring BugReportClient/ClientConfig/BugReportBindings at bootstrap, choosing providers, sanitizers, Policy, or reporters, or when initialization questions come up (init order, runZonedGuarded, flush on startup, per-environment config).

Use when configuring or debugging bug_handler sanitizers and filters - masking PII/secrets in reports, DenyListFilter/AllowListFilter paths, payload size limits, fields arriving masked that should be readable, fields arriving readable that should be masked, or compliance requirements on diagnostic data.