Troubleshooting

What the common symptoms mean and how to fix them, from a start that fails to pushes and geofences that don't arrive.

Start with Bubbl.diagnostics() and the native log at logLevel debug: see Testing and diagnostics. Most problems show up in active, registered, hasPushToken or lastError.

Bubbl doesn't start#

Symptom	Cause and fix
`Bubbl.start: the API key is empty`	Pass the SDK API key from Configuration › Developers.
`Bubbl.start: baseUrl must be https:// (http:// only for localhost or a .test host)`	Use the `https://` API address. `http://` is only for local development: see Local development over http.
`Bubbl.start: the credential is incomplete`	The key ID, secret or install ID of a device credential is empty.
`supported` false	The device is below Android 8.1 or iOS 17. Bubbl stays inactive there by design.

On Android, the native Bubbl.start throws these as an IllegalArgumentException, so they show as a crash in development. On iOS, and in Flutter and React Native, they're logged and Bubbl doesn't start.

The device doesn't register#

Symptom	Cause and fix
`registered` stays false and `lastError` mentions `invalid_key`	The API key is wrong: a typo, or another workspace's. Copy it again from Configuration › Developers.
Bubbl logs that the API key and the address don't match (`wrong_environment`) and stops	A `pk_test_` key needs the Sandbox address and a `pk_live_` key the Production one. The log says which address to use. See Sandbox and Production.
iOS: `The app can't use the Keychain (errSecMissingEntitlement)`	The build isn't code-signed (for example a Simulator build with signing turned off), and iOS gives an unsigned app no Keychain. Sign the build.
iOS: `An http:// baseUrl needs NSAllowsLocalNetworking…`	App Transport Security blocks local `http://`. In development builds only, set `NSAppTransportSecurity` › `NSAllowsLocalNetworking` to `YES`.

Registered, but nothing arrives#

Symptom	Cause and fix
Sandbox: nothing arrives, and the log says `Bubbl sandbox: approve this device with code …`	The phone is pending. Approve it under Configuration › Test Devices.
Sandbox: the log says the Sandbox has as many pending devices as it allows	Approve or remove some pending phones in the dashboard; Bubbl tries again in a few hours.
`active` false, `consentRequired` true, `consent` null	You started with `requireConsent`. Call `setConsent(true)` once the user agrees.
`active` false, `consent` false	The user opted out, or `deleteMyData()` was called.
`active` false, `pausedUntil` set	The server paused Bubbl, for example a Production key on a plan that doesn't include your own app. It retries later. Check your plan, and use the Sandbox key meanwhile.
`sdkSupported` false, and `This SDK (…) is older than the workspace's minimum` in the log	Your workspace requires a newer SDK. Update it.
`credentialRejected` true	The server refused the device credential (it was revoked, for example). Bubbl has stopped: start it with a new credential.

Push#

Symptom	Cause and fix
Android: `hasPushToken` false on the first launch only	Normal with the dashboard's `google-services.json`: Bubbl gets the Firebase settings when it first registers, and the token on the next launch or within the hour. Don't upload the file again.
Android: `hasPushToken` stays false	No Firebase: upload `google-services.json` under Configuration › Firebase › Android apps, or add it to the app together with the `com.google.gms.google-services` Gradle plugin (the file alone is ignored). Check your package name is in it.
Android: a token, but no pushes and no error	Your app's Firebase project isn't the one whose service account is in the dashboard. They must match.
Android: nothing after the user force-stopped the app	Android wakes no app after a force stop until it's opened again.
Android: `Notification not shown: the app is in the background and notifications are off`	The user hasn't allowed notifications (Android 13 and later). Ask with `Bubbl.permissions.requestNotifications()`.
iOS: `hasPushToken` false	Notifications aren't allowed yet. Bubbl asks iOS for the token once they are, at the latest the next time the app opens.
iOS: `iOS couldn't give the app a device token …`	Usually the Push Notifications capability or the provisioning profile is missing.
iOS: `The app has no delegate, so Bubbl can't get the device token`	Call `Bubbl.setPushToken` from your app delegate. See Handing over pushes yourself.
iOS: pushes don't arrive	Check the bundle ID and key under Configuration › Apple Push, and that the build's APNs environment matches: development-signed Xcode builds are sandbox; ad hoc, TestFlight and App Store builds are production.
iOS: pushes arrive without their picture	Add the notification service extension, and replace Xcode's template code in it entirely. See Pictures on iOS pushes.
Test push dropped	`active` must be true on the phone, and the device must not have opted out.

Geofences#

Symptom	Cause and fix
Geofences fire only with the app open	The user allowed location only while using the app (`backgroundLocation` false). Ask with `requestLocation` and `always` set to true.
iOS: `osWatchesGeofences` false	"Always" with precise location is needed for iOS to watch geofences itself; otherwise they're checked from location changes, which is coarser.
Android: `backgroundRestricted` true	The user restricted the app's background activity in Settings. Bubbl can't run with the app closed until they lift it.
`geofences` is 0	Location is off for Bubbl (`locationEnabled` false), permission hasn't been given, or there are no campaign locations near the device.
iOS: some events missing after a reboot	Events before the first unlock after a reboot can't be kept on iOS; `transitionsDroppedWhileLocked` counts them.

Flutter and React Native#

Symptom	Cause and fix
React Native: none of Bubbl's calls do anything	The New Architecture is off, or the app wasn't rebuilt after installing the package. The package is a TurboModule only.
React Native: `diagnostics()` says `started` false with a reason in `lastError`	There's no native module here: Expo Go, the web build, Jest, or an old build. Use a development build.
Flutter or React Native: no Bubbl logs in the Dart or JavaScript console	Bubbl logs natively: Logcat (tag `BubblSDK`) or the iOS unified log (`tech.bubbl.sdk`).
Flutter iOS: Xcode reports a dependency cycle after adding the notification service extension	In Runner › Build Phases, drag "Embed Foundation Extensions" above "Thin Binary".
Expo: prebuild fails on `cleartextHosts`	Your app already has a network security config. Add the hosts to it and leave `android.cleartextHosts` out.

Still stuck? Collect Bubbl.diagnostics() and the native log at debug level before contacting Bubbl support.

Was this page helpful?