Troubleshooting

• Capture settings not fetched yet. Uploads wait until they are. Check the device can reach your API URL (proxies, firewalls, a typo in the URL).
• Session not sampled. In production mode only ~10% of sessions record. The web SDK defaults to production; set mode: 'qa'.
• No backend in the SDK config: captures are saved locally only.
• Kill switch on: bugcapsule capture shows enabled: false.
• Wrong key: a bcs_ key in the app, or a rotated bci_ key. A rejected key stops capture for the session (Flutter and web also delete the local queue).
• Crash capsules upload on the next launch (Android, iOS). Reopen the app.
• iOS: BugCapsule.instrument(config) without BugCapsuleURLSession in integrations records no network. Uploads only run in the foreground.
• Android: missing INTERNET permission.

Your app's origin isn't allowed for your project yet. Send the exact origin (scheme, host and port) to your BugCapsule team; see Get your origin allowed.

• The capsule is larger than the project's maximum capsule size (5 MB by default; see the dashboard's capture settings). Lower maxBodyBytes or exclude large endpoints.
• A custom integration or beforeRecord hook writes values that aren't plain JSON, so the capsule is rejected. Check with bugcapsule inspect on the saved local file.
• The device is offline or BugCapsule is briefly busy: the SDK keeps the capsule in its outbox and retries for up to 7 days.

• build.gitSha: build without BUGCAPSULE_GIT_SHA (Flutter dart-define, Android Gradle property/meta-data, iOS Info.plist keys, web env), or a dirty tree.
• Missing bodies: body capture off, excluded endpoints, bodies over the limit.
• crash.persisted: written by a crash handler; expected for crashes.
• capability.input.pointer.replay on iOS: pointer-only flows. Add semantic actions.

A manual capture without a failure assertion. Add check/fail for the behaviour QA reports, so the capsule has something replay can check.

Delete the capsule in the dashboard, add the field name to Extra redaction keys in the dashboard's capture settings (it reaches every device at its next refresh and also re-redacts what's already buffered), then add it to your app's redactKeys or a beforeRecord hook. Rotate the leaked secret itself.

• A volatile field (timestamp, nonce, request id) is part of the request key: add an EndpointRule with ignoreBodyFields / ignoreQuery.
• Your fix changes which requests the app sends: strict replay can't prove a fix it never saw. Capture a capsule on the fixed path. This is correct behaviour, not a bug.
• The replayed build talks to a different host or path (environment config).

The replayed build doesn't register an id the recording used: renamed, registered later than the input, or behind a feature flag. Web: BugCapsule.action() registers its replay handler only after init.

Init isn't first (Android: not at the top of Application.onCreate, or from an App Startup initializer; iOS: something read UserDefaults before start; web: rendering before await init). Or state is registered after the first input. Or the replayed build lacks an integration the capture had.

A token or OTP was replaced on device and replayed as a placeholder, so the app took another path. Use a QA test account whose credentials aren't needed in the failing flow, or start the flow after login.

• runtime.mismatch: wrong project; use -p or --runtime.
• State schema: the app's stateSchemaVersion differs from the capsule's periodic checkpoint. Expected after a schema change; in regression suites the test becomes stale.

Recorded latency is replayed exactly, but idle compression can skip over a timer whose effect wasn't recorded. Try --no-compress-idle. Replace DateTime.now()/Date.now()/Math.random() with the SDK hooks.

• The emulator must be unlocked once after boot; AVDs with a PIN can't be unlocked by the CLI.
• testInstrumentationRunner isn't BugCapsuleReplayRunner, or the variant isn't debuggable (replay is refused).
• bootTimeoutSeconds in bugcapsule.json must be a string ("300").

• The build configuration doesn't define DEBUG (ios.configuration).
• replayTest doesn't point at your test (<UITestTarget>/BugCapsuleReplayTests/testReplay); without uiTestTarget the default target name is UITests.
• Physical devices aren't supported by the launcher; use a simulator.

• Something already serves web.url (maybe an old build). Stop it, or pass --app-url to use it deliberately.
• allowReplay is false in the build the CLI serves; set it via web.env.
• Requests to other origins (fonts, CDNs, analytics) are blocked: add static ones to web.allowOrigins; make the SDK init before code that captures fetch.

The package depends on every library it integrates with. Your app's bloc, riverpod, get, mobx, dio, http, go_router and shared_preferences versions must be inside its ranges even if you don't use them with BugCapsule.