Skip to content
Optima docs
SDKsAndroid SDK

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

  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.instance.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("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.
  4. Nothing in logcat at all — confirm Optima.isInitialized is true and that you're calling Optima.instance/Optima.track(...) after Optima.init actually ran (a call before init logs 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 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 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

  1. Screen name vs. targeting mismatch. Confirm the screen name you're passing to screen(name) (or the Activity simple 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://<package>/<screen> URL (chapter 5). A rename of an Activity 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 (content.register 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 composition 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.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 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 = ConsentSource.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.

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.

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 own optima-action:// URLs. Use data-link / data-actiontype="close" attributes instead; hand-built optima-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:

  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.instance.deviceId a plausible UUID and stable across app restarts? If it's changing on every launch, something is clearing SharedPreferences 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. 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.

On this page