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
- Unmapped
screen_view(or any category). Thetrack/screenresponse'sdroppedarray (surfaced in thetrackevent) names this asunknown_category. See chapter 2 for the exact mapping to create; every custom category needs its own mapping the same way. - Wrong-platform key. The key must be created on the
mobileplatform in the console (chapter 2). Aweb- platform key will often still authenticate at the header-check layer but then behave strangely for content/identity resolution — see401/403below if you're seeing outright auth failures rather than just "content never matches." - Consent buffering. With
consent.beforeDecision = "buffer"(the default) and no decision yet, hits queue but never flush — checkOptima.instance.consent.get().decidedAt. This is a client-side hold, distinct from the server's collection gate below. missing_consent(server-side) — the collection gate (CONSENT_COLLECTION_GATE) is inrequiremode for this event type and the necessary consent purpose hasn't been granted (or was explicitly withdrawn). CheckOptima.instance.consent.get().decisionsagainst 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.- An
error {op: "track"}event fired. Check itscause; 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. - Nothing in the console at all. A call made before
Optima.initresolves is queued and replays silently once it succeeds — that's expected, not a bug (see chapter 1), sotrackcalls issued early are not the problem by themselves. If hits still never arrive well afterinitshould have settled, confirmOptima.initwas 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 failedinit, 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
mobileplatform 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
- Screen name vs. targeting mismatch. Confirm the screen name you're
passing to
screen(name)is actually what the operator targeted — campaignmobile_inappitems match the literalscreenstring, and operator items match a glob against the derivedapp://<appId>/<screen>URL (chapter 5). - 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.
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 forweb_personalization-only responses (dropped silently, see chapter 5) or an unregistered structured type routed to acontent:itemevent instead of aPresentation(content.registerit, or check for thecontent:itemevent if you're handling it that way).- Remember the no-slot caveat: an
inlineitem with no matchingOptimaSlotin your tree renders nowhere, even though it did load — check for acontent:loadedevent with `count0` and nothing visible, which is the signature of this specific trap.
Banner never shows
deviceIdis empty or changing on every launch. IfOptima.instance.deviceIdis"",inithasn't completed successfully — check for the"Optima.init failed"warning. If it's a plausible UUID but changes on every restart, something is clearing yourStorageport between runs (a test harness, an aggressive backup/restore, or a strayreset()call you didn't intend).- Already answered. If
consent.get().decidedAt !== undefined, the server simply stops returning thebanner_consentitem — this is correct behaviour, not a bug. CallOptima.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 servedbanner_consentitem surfaces as a plaincontent:itemevent 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 setsource: "cmp"in yourOptimaConfig.
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_openabsent from the payload.push.trackOpencorrectly does nothing and returnsfalseif 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.trackOpennever actually called. Confirm it's wired into whichever ofonNotificationOpenedApp/getInitialNotification(@react-native-firebase/messaging) oraddNotificationResponseReceivedListener/getLastNotificationResponseAsync(expo-notifications) your app uses — see the two recipes in chapter 7.- A
404/5xxfromGET /edge/v1/o/{token}is logged at debug only, never surfaced as anerrorevent (a missed open record shouldn't disturb the app) — enabledebug: trueto 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.
- Is
debugoutput showing503responses, specifically, across multiple endpoints at once? → backend NATS issue, not an SDK issue. - Is it one endpoint only (say, only
nba/responses)? → check that endpoint's specific kill switch first — see the404NBA behaviour. - Is
Optima.instance.deviceIda plausible UUID and stable across app restarts? See Banner never shows above for what a changing device id usually means. - 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.