Skip to content
Optima docs
SDKsiOS SDK

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

  1. unknown_category — the track/screen response's dropped array (surfaced in the .track event) 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 exact screen_view mapping to create; every custom category needs its own mapping the same way.
  2. missing_consent — the collection gate (CONSENT_COLLECTION_GATE) is in require mode for this event type and the necessary consent purpose hasn't been granted yet (or was explicitly withdrawn). Check Optima.shared.consent.get().decisions against the required purpose in the console's event-type configuration. This is a server-side collection gate, distinct from the client-side beforeDecision = .buffer buffering — a hit can clear the client-side buffer and still be dropped server-side for this reason.
  3. An .error(op: "track", cause:) event fired — check its cause; 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.
  4. Nothing in the log at all — confirm Optima.isInitialized is true and that you're calling Optima.shared/Optima.track(...) after Optima.initialize actually ran (a call before initialize logs 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 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 — if you're seeing 401/403 specifically (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

  1. Screen name vs. targeting mismatch. Confirm the screen name you're passing to screen(name) (or the view controller's type name under .auto tracking) 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://<bundle-id>/<screen> URL (chapter 5). A rename of a view controller class, under .auto tracking, silently changes what screen name gets reported.
  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. .contentLoaded(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 plain .contentItem event instead of a Presentation (register a renderer for it, or check for the .contentItem event if you're handling it that way).
  4. Remember the no-slot caveat: an .inline item with no matching OptimaSlot in your view hierarchy renders nowhere, even though it did load — check for a .contentLoaded event with count > 0 and nothing visible, which is the signature of this specific trap.
  • Already answered. If consent.get().decided == true, the server simply stops returning the banner_consent item — this is correct behaviour, not a bug. Call Optima.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 served banner_consent item surfaces as a plain .contentItem 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.

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:

  1. Is debug log 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/config first (see the 404 section above for NBA's).
  3. Is Optima.shared.deviceId a plausible UUID and stable across app restarts? If it's changing on every launch, something is clearing UserDefaults between runs (a test harness, an aggressive backup/ restore, or an explicit reset() call you didn't intend) — check for stray reset() calls before assuming a transport problem.
  4. Confirm you're on a real device or a simulator with network access — URLSession errors (offline, a captive portal, a proxy misconfiguration) surface as .retry(status: nil, cause:) internally and follow the same backoff ladder as a 5xx; they never crash or throw into your app, but they also never succeed until connectivity returns.

On this page