Troubleshooting

Problem: the app installs, but the SDK will not initialize, so no session can start.

Cause: a device that is not enrolled, or whose entitlement was revoked, cannot activate — initialization failure is usually an entitlement or billing-state problem, not an install problem.

Check: confirm the device was enrolled from the customer portal for the right site, and look at the portal device state (pending, active, payment grace, deactivated, revoked).

Solution: complete enrollment in the portal. A device in pending enrollment does not consume a seat, so you can finish setup before committing a license. Do not reinstall the app — reinstalling does not fix entitlement state.

Problem: the frame was accepted, but the observation list is empty.

Cause: an empty list is a valid no-decode result. Native absence, malformed decoder output, or an undecoded frame never produces a sample GTIN — the SDK refuses to invent data. The GS1 decode contract documents the full deterministic path.

Check: the submit return value is a native status code, not a barcode count. Confirm the frame was actually accepted before you chase the empty result.

Solution: adjust the capture — another angle or a focused scan — and submit again. Never treat an empty result as an error.

Problem: a previously working device stops scanning with no app-side change.

Cause: the entitlement changed — the device may have moved into payment grace, been deactivated or revoked, or the licensed quantity no longer covers the seats in use.

Check: the device state in the portal first — pending, active, payment grace, deactivated, revoked — and compare the licensed quantity against the seats in use.

Solution: resolve it in the portal: restore billing to clear a grace state, or reactivate the device. Check the portal before reinstalling anything.

Problem: the portal shows free seats, but the new device fails to activate.

Cause: the device is still in pending enrollment — it has not received its signed entitlement yet.

Check: the portal device state for the new device.

Solution: complete enrollment from the customer portal for the site the device belongs to. When enrollment completes, the operations portal issues the signed device entitlement license.

Problem: the scanner fires, but scan output never reaches your app.

Cause: DataWedge integration works through broadcast intents. If the host is not registered for the DataWedge broadcast action, results never arrive — the scan itself works, the handoff is broken.

Check: DataWedge 8.2 or newer, with its profile assigned to your host application, and confirm the host registered for the DataWedge broadcast action.

Solution: register the host for the broadcast action, then map the scan output to canonical observations and render only GTIN-scoped evidence. See the Zebra quickstart for the wiring.

Problem: one label never decodes, while others scan fine.

Cause: a hidden or damaged label — or malformed input that fails deterministically instead of producing a guess.

Check: try another angle or a focused scan on the same label.

Solution: a single label often needs a focused scan from another angle. If it still never decodes, the label itself is the problem — reprint or replace it, because repeated scanning of an unreadable label will not help.

Problem: you see lot, serial, or expiration evidence but no qualified GTIN.

Cause: a lot, serial, or expiration value without a qualified GTIN is temporary evidence, not a receivable item. GTIN is the primary identity; everything else is GTIN-scoped — see the GTIN-first principle in Platform concepts.

Check: confirm whether the evidence is OCR-derived (the isOcrRescue flag marks OCR-derived evidence).

Solution: do not receive on partial evidence — rescan for the GTIN.

Problem: one physical label is counted more than once.

Cause: repeated video frames are not quantity — each frame is capture evidence, not a separate item.

Check: whether your receiving logic keys on raw frames or on the checkpointed canonical event.

Solution: key receiving on the canonical event, not on raw frames. See canonical JSON events.

Problem: a GTIN-shaped value is rejected during validation.

Cause: a check-digit mismatch. A GTIN must pass modulo-10 check-digit validation before it counts as a GTIN.

Check: run the modulo-10 check-digit validation against the value, exactly as the label carries it.

Solution: rescan the label — a single misread digit fails the check. If the value fails repeatedly, the label is misprinted; reprint it.

Problem: the GTIN came from OCR and the workflow routes it to review instead of committing it.

Cause: that is the policy, not a bug. OCR-only GTIN or serial evidence requires review and must not auto-commit.

Check: the isOcrRescue flag — it marks OCR-derived evidence.

Solution: route OCR-only evidence to review. Never auto-commit it; a barcode rescan is the way to promote it to a first-class observation.

Problem: the API answered with an error, and you need to know what it means.

Cause: API errors are reported as RFC 9457 problem documents carrying a stable machine-readable code and a correlationId.

Check: read the code field — it is the stable part of the contract, not the human-readable message.

Solution: branch on the code to decide what to do next, and include the correlationId when you contact support. See API overview for the error concepts.