Troubleshooting

Organised by symptom. Start with the one that matches what you see.

Nothing arrives in the dashboard at all#

Work through these in order — the first three account for most cases.

1. 1

   Confirm init actually ran and resolved

   init() returns a promise. If it is called inside a component that unmounts, or its rejection is swallowed, capture never starts.

   TypeScriptCopy

   await ScaleBun.init({ /* … */ verbose: true });console.log('ScaleBun initialised');

   verbose: true logs the bootstrap. If you do not see it, the call site is the problem, not the SDK.

2. 2

   Check the credentials and the base URL

   Three values must match the app environment you are looking at in the dashboard: projectId, publishableKey, apiBaseUrl.

   The most common mistake is a key from a different environment than the one you are viewing. Client keys are prefixed for exactly this reason — skb_test_ck_… data will never appear under production.

   Read apiBaseUrl from the dashboard's SDK setup panel rather than hard-coding it.

3. 3

   Confirm the app and environment are enabled

   A disabled app or environment rejects ingestion with 401. Check Workspace → Apps.

4. 4

   Rule out the network

   Corporate proxies and ad-blocking DNS on device can drop requests. Try a different network. With verbose: true the transport logs failures.

A session appears but looks half-empty#

This is expected behaviour today, not a misconfiguration.

The SDK maintains two session lanes — an analytics session (always-on, canonical, created at cold start) and a recording session (frames and journey events). Both open a backend session row, and the recording row references the analytics session id.

The consequence: track() events land on the analytics row, while frames and journey events land on the recording row. A view that reads only one row looks half-empty.

Events stop after backgrounding, then resume oddly on iOS#

Fixed in the SDK, but worth knowing if you are on an older version.

iOS suspends the process on background, so a network request issued during teardown may never resolve until the next foreground. An earlier version cleared the analytics session id only after awaiting that request, so the resume guard never saw a cleared id and never opened a new session — every close-and-reopen produced no new analytics session.

The fix clears the id synchronously before any await. If you see events only on cold start and never on resume, upgrade.

Screen names are missing or wrong#

Set the navigation ref once, at the top of your app:

ScaleBun.setNavigationRef(navigationRef);

Without it, the SDK falls back to slow heuristic polling, which produces late or missing screen names. Setting the ref installs an explicit navigation listener.

If you cannot use a ref, name screens explicitly with <ScaleBunScreen> or useScaleBunScreen().

Session replay produces no frames#

Confirm the lane is live:

ScaleBun.replay.isRecording;  // booleanScaleBun.replay.sessionId;    // string | null

In-app messages or test sends do not appear again#

Frequency caps, dismissals and impressions are persisted on device, which is correct in production and inconvenient while testing. Reset that state without reinstalling:

ScaleBun.engage.resetInAppState();

It clears the throttle store and the one-shot test-seen store, and returns the number of cleared entries. The device id is untouched, so identity is preserved.

To see what the backend is actually serving this device right now:

const messages = await ScaleBun.engage.debugFetchInAppMessages();

Both are development helpers. Neither should ship in a release build path.

Push notifications are not delivered#

Run the doctor first — it replicates the SDK's adapter-selection logic and reports the exact gap:

npx scalebun doctor

Then check, in order: notification permission was granted; a token exists (ScaleBun.push.getToken()); the adapter selected is the one you expect (ScaleBun.push.status()); and the FCM/APNs credentials are configured in Workspace → Integrations.

Nothing above matches#

Enable the desktop debugger for live inspection of the transport and capture lanes:

await ScaleBun.init({  projectId: '…',  publishableKey: '…',  apiBaseUrl: '…',  desktopDebug: true,  verbose: true,});

Then contact support with: SDK version, React Native version, platform, whether the new architecture is enabled, and the verbose log around initialisation.

Related#

• Install — requirements and native setup.

• Configuration — every option and its default.

• Quick start.