Skip to content
Optima docs
SDKsReact Native SDK

Troubleshooting

React Native SDK v1.2.0 — Troubleshooting

Start every investigation the same way: set debug: true (chapter 1) and watch your Metro/device console for the [optima] prefix. Every enqueue, flush, server response, and internal error logs a line, and every failure the SDK swallows for you (per the guarantee that no public call ever throws into your app) still produces a log line and an error event — the two places to look are always "what does the console say" and "did an error {op, cause} event fire" (see chapter 3).

Nothing lands

  1. Unmapped screen_view (or any category). The track/screen response's dropped array (surfaced in the track event) names this as unknown_category. See chapter 2 for the exact mapping to create; every custom category needs its own mapping the same way.
  2. Wrong-platform key. The key must be created on the mobile platform in the console (chapter 2). A web- platform key will often still authenticate at the header-check layer but then behave strangely for content/identity resolution — see 401/403 below if you're seeing outright auth failures rather than just "content never matches."
  3. Consent buffering. With consent.beforeDecision = "buffer" (the default) and no decision yet, hits queue but never flush — check Optima.instance.consent.get().decidedAt. This is a client-side hold, distinct from the server's collection gate below.
  4. missing_consent (server-side) — the collection gate (CONSENT_COLLECTION_GATE) is in require mode for this event type and the necessary consent purpose hasn't been granted (or was explicitly withdrawn). Check Optima.instance.consent.get().decisions against the required purpose in the console's event-type configuration. A hit can clear the client-side buffer above and still be dropped server-side for this reason.
  5. An error {op: "track"} event fired. Check its cause; a terminal 4xx response body is included in the debug log line (truncated to 200 chars) and usually names exactly what's wrong with the batch.
  6. Nothing in the console at all. A call made before Optima.init resolves is queued and replays silently once it succeeds — that's expected, not a bug (see chapter 1), so track calls issued early are not the problem by themselves. If hits still never arrive well after init should have settled, confirm Optima.init was actually called at all (a conditional/early-return that skips it is a common culprit) and check for the one "Optima used without an initialized SDK; calls are no-ops" warning — it fires only after a failed init, exactly once no matter how many no-op calls followed it.

401 / 403 Unauthorized / Forbidden

Almost always one of:

  • Wrong key platform. The key must be created on the mobile platform in the console (chapter 2). An operator can also restrict a key to a specific origin/App ID allowlist that your app's requests won't satisfy.
  • Revoked key. Keys can be revoked from the console at any time; a revoked key's requests are rejected immediately, with no grace period.

A 401/403 on /edge/v1/track also clears the entire local outbox — not just the offending batch. If you fix the key afterward, hits queued before the fix are gone; this is deliberate (retrying against a key that will never be accepted would otherwise wedge the outbox forever), but it means "fix the key, then generate fresh hits to confirm" rather than expecting the old backlog to flush.

429 behaviour

Expected, not a bug: the SDK backs off on the retry ladder (1s → 2s → 5s → 15s → 60s, or the server's Retry-After header if present, whichever is more specific) and retries automatically. A 429 never drops a batch or fires an error event on its own — only a subsequent terminal (4xx, not 429) response would. If you're seeing sustained 429s, that's a sign your overall rate limit for the key is being throttled — check edge_key_rpm/edge_ip_rpm on the backend side, not something to work around client-side.

Content is empty when you expect items

  1. Screen name vs. targeting mismatch. Confirm the screen name you're passing to screen(name) is actually what the operator targeted — campaign mobile_inapp items match the literal screen string, and operator items match a glob against the derived app://<appId>/<screen> URL (chapter 5).
  2. Licence gating. On-site campaign content and some content types are gated by the tenant's licence configuration server-side; an unlicensed feature simply never returns items, with no error surfaced to the device — this is an operator/account-level question, not something to debug client-side.
  3. content:loaded {slot, count} says 0 but you expected items — the fetch succeeded and returned nothing that resolves to a presentation on this platform. Check for web_personalization-only responses (dropped silently, see chapter 5) or an unregistered structured type routed to a content:item event instead of a Presentation (content.register it, or check for the content:item event if you're handling it that way).
  4. Remember the no-slot caveat: an inline item with no matching OptimaSlot in your tree renders nowhere, even though it did load — check for a content:loaded event with `count

    0` and nothing visible, which is the signature of this specific trap.

  • deviceId is empty or changing on every launch. If Optima.instance.deviceId is "", init hasn't completed successfully — check for the "Optima.init failed" warning. If it's a plausible UUID but changes on every restart, something is clearing your Storage port between runs (a test harness, an aggressive backup/restore, or a stray reset() call you didn't intend).
  • Already answered. If consent.get().decidedAt !== undefined, the server simply stops returning the banner_consent item — this is correct behaviour, not a bug. Call Optima.instance.reset() in a debug build to re-test the first-run flow, or clear your app's storage.
  • consent.source = "cmp". Under this config the built-in banner never renders at all, by design — a served banner_consent item surfaces as a plain content:item event for your own CMP UI to handle instead. If you expected the built-in banner and it's not appearing, double-check you didn't set source: "cmp" in your OptimaConfig.

HTML items missing

If display.htmlMode resolved to "off" (either because you set it, or because react-native-webview isn't installed — check your console for the one-time "react-native-webview is not installed; ..." warning at init), unstructured items never become a Presentation — they surface only as content:item {slot, item} events. Install react-native-webview (and, on bare RN, run pod install) if you want the built-in renderer; otherwise handle the content:item event yourself. See chapter 1 and chapter 5.

unknown_category in track events

Any category — screen_view or your own (add_to_cart, purchase, ...) — needs an explicit category mapping in the Optima console before it's visible in analytics. An unmapped category is not an error: the hit is accepted, but the response's dropped array names it, and the track event's dropped field carries that same list through. See chapter 2.

Push opens not recorded

  • optima_open absent from the payload. push.trackOpen correctly does nothing and returns false if the push wasn't built by Optima's delivery pipeline, or if open tracking was off for that template — see chapter 7. This is not an error state.
  • push.trackOpen never actually called. Confirm it's wired into whichever of onNotificationOpenedApp/getInitialNotification (@react-native-firebase/messaging) or addNotificationResponseReceivedListener/getLastNotificationResponseAsync (expo-notifications) your app uses — see the two recipes in chapter 7.
  • A 404/5xx from GET /edge/v1/o/{token} is logged at debug only, never surfaced as an error event (a missed open record shouldn't disturb the app) — enable debug: true to see it.

Storage errors (error {op: "storage"})

A Storage port failure — at hydration, or on any subsequent write — falls back to an in-memory-only store for the rest of the process, firing exactly one error {op: "storage", cause} event for the life of that store (a failure permanently disables further storage attempts rather than retrying and re-failing). No log line accompanies it — a storage failure never calls logger.warn/debug, so an app that isn't listening for error events won't see anything in its console at all, even with debug: true. Everything keeps working for the life of the process (device id, consent, the outbox, …), but nothing survives a restart. Look for this event if hits/consent/device id all reset on every launch despite AsyncStorage (or your injected Storage port) appearing to work elsewhere in your app — it's a sign the specific keys the SDK writes (_optima_*) are hitting a full-disk, permissions, or corruption issue your own app's storage usage isn't.

"Nothing errors, but nothing arrives" checklist

NATS down on the backend means every /edge/v1/* write endpoint answers 503, not a slow timeout — the gateway's publish ack to JetStream is its durability point, so it never buffers a write it can't durably queue. From the SDK's side this looks exactly like any other retryable failure (the backoff ladder engages, an error event eventually fires if the ladder is exhausted) — there is nothing SDK-side to fix. If you're seeing a burst of 503s across every endpoint (track, identify, consent, forms/submit, nba/responses) simultaneously, rather than one endpoint specifically, that's the signature to hand to whoever operates the backend, not something to chase in the app.

  1. Is debug output showing 503 responses, specifically, across multiple endpoints at once? → backend NATS issue, not an SDK issue.
  2. Is it one endpoint only (say, only nba/responses)? → check that endpoint's specific kill switch first — see the 404 NBA behaviour.
  3. Is Optima.instance.deviceId a plausible UUID and stable across app restarts? See Banner never shows above for what a changing device id usually means.
  4. Storage failures fall back to in-memory twins and fire one error {op: "storage"} event (no log line) — see Storage errors above.

Debugging with debug: true and on("error")

The two tools you always have, together: debug: true gets you every enqueue/flush/response as a log line; Optima.instance.on("error", (e) => console.warn(e.op, e.status, e.cause)) gets you a structured feed of every guarded failure without scrolling through a verbose log. debug itself is fixed at init time — it's resolved once into the immutable ResolvedConfig (see chapter 2) and there is no live toggle after that, since a second Optima.init call is always a no-op; wire it to __DEV__ (fixed per build already, so this needs no runtime toggle at all) rather than a remote feature flag, since flipping a remote flag while the app is running won't change an already-initialized SDK's debug value — only a fresh process start with the new value would. on("error") has no such restriction and can be registered from anywhere, including a crash-reporting integration you want every SDK failure fed into.

On this page