Troubleshooting
iOS SDK v1.4.0 — Troubleshooting
Start every investigation the same way: set debug = true
(chapter 1) and watch the device
log for the com.optima.sdk subsystem. Every enqueue, flush, server
response, and internal error logs a line under that tag, 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 log say" and "did an
.error(op, cause) event fire" (see chapter 3).
Hits not appearing in analytics
unknown_category— thetrack/screenresponse'sdroppedarray (surfaced in the.trackevent) will name this. It means the category (screen_view, or your own) has no mapping configured in the Optima console yet. See chapter 2 for the exactscreen_viewmapping to create; every custom category needs its own mapping the same way.missing_consent— the collection gate (CONSENT_COLLECTION_GATE) is inrequiremode for this event type and the necessary consent purpose hasn't been granted yet (or was explicitly withdrawn). CheckOptima.shared.consent.get().decisionsagainst the required purpose in the console's event-type configuration. This is a server-side collection gate, distinct from the client-sidebeforeDecision = .bufferbuffering — a hit can clear the client-side buffer and still be dropped server-side for this reason.- An
.error(op: "track", cause:)event fired — check itscause; a terminal 4xx response body is included in the debug log line (truncated to 200 characters) and usually names exactly what's wrong with the batch. - Nothing in the log at all — confirm
Optima.isInitializedistrueand that you're callingOptima.shared/Optima.track(...)afterOptima.initializeactually ran (a call beforeinitializelogs one warning,"Optima used before initialize; call dropped", and is otherwise silent — check for that specific line).
401 or 403
Almost always one of:
- Wrong key platform. 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 — if you're seeing401/403specifically (not just "content never matches"), double-check the platform first anyway, since an operator can also restrict a key to a specific origin/App-ID allowlist that a mobile 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.
413 on /edge/v1/track (batch too large)
If the gateway refuses a batch as too large (413), the SDK keeps the hits,
halves the batch and resends, down to a single hit (a 400 is bisected the same way, so one
malformed hit cannot take its neighbours with it). Only a single hit that is
still refused is dropped, with an .error event for track. You do not need
to do anything client-side. The cap on hits per batch is the operator's
edge_max_hits_per_batch setting, which cannot go below the SDK's own batch
size of 20, so a 413 on a normal batch usually means an unusually large hit
body or a proxy in front of the gateway with a small body limit.
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 the device
(or, more likely, your operator's overall rate limit for the key) is being
throttled — check edge_key_rpm/edge_ip_rpm on the backend side.
Content is empty when you expect items
- Screen name vs. targeting mismatch. Confirm the screen name you're
passing to
screen(name)(or the view controller's type name under.autotracking) is actually what the operator targeted — campaignmobile_inappitems match the literalscreenstring, and operator items match a glob against the derivedapp://<bundle-id>/<screen>URL (chapter 5). A rename of a view controller class, under.autotracking, silently changes what screen name gets reported. - 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.
.contentLoaded(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 a plain.contentItemevent instead of aPresentation(register a renderer for it, or check for the.contentItemevent if you're handling it that way).- Remember the no-slot caveat: an
.inlineitem with no matchingOptimaSlotin your view hierarchy renders nowhere, even though it did load — check for a.contentLoadedevent withcount > 0and nothing visible, which is the signature of this specific trap.
Banner not showing
- Already answered. If
consent.get().decided == true, the server simply stops returning thebanner_consentitem — this is correct behaviour, not a bug. CallOptima.shared.reset()in a debug build to re-test the first-run flow, or delete and reinstall the app. consent.source == .cmp. Under this config the built-in banner never renders at all, by design — a servedbanner_consentitem surfaces as a plain.contentItemevent 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 = .cmpin yourOptimaConfig.
NBA responses silently stop working (404)
Once nba.respond(...) receives a single 404 from the server, the queue
disables itself for the rest of the process's lifetime — this is the
operator's edge_nba_responses_enabled kill switch, treated as "not
available right now" rather than a transient failure worth retrying. A debug
log line names it exactly: "nba responses are disabled by the operator (404); no further sends this process". If the operator has since
re-enabled the feature, the next process start (not the current one) picks
it back up.
Buffer mode: "nothing sends"
If consent.beforeDecision == .buffer (the default) and no decision has ever
been made, tracking, identify, and content report calls all queue but never
flush — this is expected, not a bug. Check Optima.shared.consent.get().decided;
if it's false, the fix is either to present the consent banner (or your own
consent UI) so a real decision gets made, or, if consent genuinely doesn't
apply to your deployment, to configure consent.beforeDecision = .send at
init time instead of waiting on a decision that will never come.
"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. Checklist, in order:
- Is
debuglog output 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/config first (see the404section above for NBA's). - Is
Optima.shared.deviceIda plausible UUID and stable across app restarts? If it's changing on every launch, something is clearingUserDefaultsbetween runs (a test harness, an aggressive backup/ restore, or an explicitreset()call you didn't intend) — check for strayreset()calls before assuming a transport problem. - Confirm you're on a real device or a simulator with network access —
URLSessionerrors (offline, a captive portal, a proxy misconfiguration) surface as.retry(status: nil, cause:)internally and follow the same backoff ladder as a5xx; they never crash or throw into your app, but they also never succeed until connectivity returns.