Troubleshooting
Android SDK v1.4.0 — Troubleshooting
Start every investigation the same way: set debug = true
(chapter 1) and watch adb logcat -s optima:V. 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 logcat say" and "did an Error(op, cause) event fire" (see
chapter 3).
Hits not appearing in analytics
unknown_category— thetrack/screen-Response'sdroppedarray (surfaced in theTrackevent) 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.instance.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("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 logcat at all — confirm
Optima.isInitializedistrueand that you're callingOptima.instance/Optima.track(...)afterOptima.initactually ran (a call beforeinitlogs one warning,"Optima used before init; call dropped", and is otherwise silent — check for that specific line).
401 / 403 Unauthorized / Forbidden
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 OptimaEvent.Error 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 instance 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 Activity simple name underAUTOtracking) is actually what the operator targeted — campaignmobile_inappitems match the literalscreenstring, and operator items match a glob against the derivedapp://<package>/<screen>URL (chapter 5). A rename of an Activity class, underAUTOtracking, 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 plainContentItemevent instead of aPresentation(content.registerit, or check for theContentItemevent if you're handling it that way).- Remember the no-slot caveat: an
INLINEitem with no matchingOptimaSlotin your composition renders nowhere, even though it did load — check for aContentLoadedevent 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.instance.reset()in a debug build to re-test the first-run flow, or manually clear the app's data. consent.source = CMP. Under this config the built-in banner never renders at all, by design — a servedbanner_consentitem surfaces as a plainContentItemevent 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 = ConsentSource.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.
Robolectric and the first-run toolchain download
The Compose module's Robolectric tests (banner two-stage flow, in-app
dismiss/click reporting) download an Android platform jar the first time
they run in a fresh environment — this can take noticeably longer than a
normal ./gradlew test invocation on a clean cache and is not a hang; give
it a few minutes on first run in CI or a fresh checkout. Subsequent runs use
Gradle's cache and are fast.
A data-link or close button in an HTML item does nothing
Check logcat for tag optima:
content link blocked (no user activation)— the link was not triggered by a tap or key press on the item (an auto-redirect, a timer, or a click synthesized by script). Since 1.2.1 only user-initiated links open.html bridge: unauthenticated optima-action ignored— something other than the SDK's injected script sent a bridge signal, usually an embedded iframe or a page that builds its ownoptima-action://URLs. Usedata-link/data-actiontype="close"attributes instead; hand-builtoptima-action://URLs are not supported.
"Nothing errors, but nothing arrives" checklist
The same failure mode the backend's PgBouncer-adjacent docs describe for
Postgres pooling shows up here in a NATS-shaped form: 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.instance.deviceIda plausible UUID and stable across app restarts? If it's changing on every launch, something is clearingSharedPreferencesbetween 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. - Storage failures (a full disk, a corrupted preferences file) fall back to
in-memory twins with one
warn-level log line — everything keeps working for the life of the process, but nothing survives a restart. Look for that warning if hits/consent/device id all reset on every launch.