Skip to content
Polaris Express Docs

Diagnose an NFC scan failure

When an operator-staffed iPhone running expreScan shows a red-x error after an NFC tap, you need to identify which of the five error variants the device hit and decide whether the fix is at the device, the card, or the backend. This runbook walks you through reading the error screen, opening the on-device Diagnostics sheet, and confirming connectivity before you ask the customer to try again.

Prerequisites

Section titled “Prerequisites”
  • You have physical access to the iPhone running expreScan, or a remote operator who can read the screen and tap for you.
  • The device is signed in to an admin account. The Diagnostics sheet is only reachable from Settings when the signed-in account is an admin — the link card is hidden in customer mode.
  • You know the ChargeBox the device was scanning for. You’ll need it to cross-check sync runs in the web console.

Procedure

Section titled “Procedure”

  1. Read the error variant on screen

    The error screen auto-dismisses back to ready after 10 seconds; a white countdown ring in the top-right shows time remaining. If the ring is almost empty, tap the back chevron in the top-left to hold the screen, or ask the operator to read the title before it disappears.

    There are five variants. The title text is the fastest way to identify which one:

    • Scan timed out — no card was seen. Card was not held close enough, or not long enough.
    • Card not supported — the card was read but isn’t a recognized EV card.
    • Couldn’t reach ExpressCharge — the device is offline or the API is unreachable.
    • Scan expired — the scan-arm window closed before the tap. No retry button; the operator must arm a new scan.
    • Signed out — an admin revoked this device. The button reads “Sign in”.

  2. Open Diagnostics

    Dismiss the error (tap the back chevron, or let the countdown expire). From the ready screen, open Settings, then tap Diagnostics.

  3. Check the Connection card

    The first card is Connection. Read these four values:

    • Status pill — Online, Connecting, Reconnecting, or Offline.
    • Reconnects — count since the session started. A number that ticks up while you watch means the device is flapping.
    • Last sync — relative time. Should be within the last few seconds when Online.
    • Pending uploads — scan results queued locally. Non-zero means prior scans haven’t been delivered to the backend yet.

    If status is anything other than Online and you saw a Couldn’t reach ExpressCharge error, the diagnosis is network. Skip to step 5.

  4. Check the Device card

    Scroll to the Device card. Note:

    • Push permission — should be Authorized. Denied means the device won’t receive scan-arm notifications and you’ll see Scan expired errors a lot.
    • APNs environment — sanity-check this matches the build you expect (production vs. sandbox).
    • Server — confirm this points at the right backend. Tap the copy icon to copy it into a bug report.
    • Device ID — copy this; you’ll need it to find sync runs in the web console.

  5. Run a test sync

    Scroll to the Test card and tap Run test sync. This forces an immediate device-state sync against the server using the device’s bearer token. The button shows a spinner while in flight, then a toast reports Sync OK or Sync failed.

    • Sync OK confirms bearer auth and connectivity are healthy. The failure was either card-side (unsupported card, timeout) or scan-arm timing.
    • Sync failed confirms the device cannot reach the backend with its current credentials. Continue to step 6.

  6. Match the error to the fix

    Error variantLikely causeOperator action
    Scan timed outCard not close enoughAsk customer to hold card to the top of the iPhone and re-arm.
    Card not supportedWrong card type, or idTag not provisionedVerify the EV card is registered in the web console.
    Couldn’t reach ExpressChargeDevice offline or backend unreachableConfirm via Connection card; if Online, escalate.
    Scan expiredScan-arm window elapsedRe-arm scan from the web console.
    Signed outDevice token revoked by adminSign in again from the error screen’s primary button.

Verify

Section titled “Verify”
  • The Connection card shows Online with a fresh Last sync timestamp.
  • Pending uploads is zero, or trending toward zero on subsequent refreshes (pull down to refresh the sheet).
  • A repeat scan with a known-good EV card produces a green success state, not the red-x error.
  • In the web console, the device’s most recent sync run for this Device ID is recent and successful.

If something goes wrong

Section titled “If something goes wrong”

Audit and reversibility

Section titled “Audit and reversibility”

This runbook is read-only on the device itself — running a test sync and copying diagnostics values do not modify state. The only state-changing action available from the error flow is Sign in on the tokenRevoked variant, which creates a fresh device session. That sign-in is logged through the normal device-registration audit trail.

If you copied logs to clipboard via the Recent logs card’s copy button, those logs are also retained server-side once the drain flushes — tapping the up-arrow icon on the Recent logs card forces a flush immediately.

Section titled “Related”