> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.chrt.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.chrt.com/_mcp/server.

# Troubleshooting

> A checklist of common driver-app problems and how to resolve them — location not updating, accept failures, POD upload failures, sign-in errors, and excessive battery use.

This page covers the most common driver-app issues and what to try first.
If nothing here helps, message your dispatcher or
[hi@chrt.com](mailto:hi@chrt.com) — include your app version and build
number from **Settings** > **Build Information**.

## Can't sign in

**The Sign In button does nothing or returns to the splash screen.**

* Make sure you have a working internet connection.
* Sign-in uses the device's system browser. If you've blocked third-party
  cookies for the browser globally, sign-in can fail silently. Try again
  on a default browser configuration.
* If the splash says **WorkOS client ID is missing for this build**, you
  have a non-production build. Install from the App Store or Play Store.

**Sign-in completes but the app shows "Unable to load driver profile."**

* Your account exists but doesn't have a driver record on the org you
  signed in under. Contact your dispatcher — they may have invited you
  but not yet created your driver profile, or you signed in under the
  wrong org.
* The **Try Again** button retries the driver fetch; the **Sign Out**
  button clears the session.

**A "this account isn't a driver" screen blocks you.**

* The org you signed in under doesn't permit the driver app (typically a
  shipper-only org). Switch orgs from the screen, or sign out and back in
  under the correct org.

## Can't accept an order

**The Accept button doesn't respond or returns an error.**

* Pull to refresh the offer screen. The offer may have been retracted by
  dispatch.
* Check signal. On iOS, accept needs a live connection. On Android, accept
  works offline — but verify the offline banner shows the queued change
  syncing once you reconnect.
* If accept consistently fails on a strong connection, message your
  dispatcher — there may be a server-side state issue with the task
  group.

**The offer doesn't appear at all.**

* Pull to refresh the **Offers** tab.
* Confirm you're on the right org (check **Settings** > **Organization**).
* Check that you have notifications permission and the right notification
  preferences — see [Settings](/app/settings#3-manage-notification-permissions).
* Ask dispatch to confirm the order is assigned to you, not a teammate.

## Location not updating

**Dispatch says they can't see my location.**

Work through this checklist in order:

1. Open **Settings** in the app. Is **Share Location with Dispatch**
   toggled on?
2. The permission status row above the toggle — does it say **Location
   Permission: Always** (iOS) or **Allow all the time** (Android)? If
   not, tap **Settings** on that row and escalate the permission.
3. Is the accuracy row showing **Approximate**? Tap **Enable** to switch
   to precise.
4. Is the task group **In Progress**? Location only streams for active
   orders. Tap **Start** on the task group if you haven't already — see
   [Accepting orders](/app/accepting-orders#4-start-driving).
5. Did you force-quit the app (swipe it off the recents list)? Background
   location stops on force-quit. Reopen the app.

**Location worked, then stopped.**

* iOS Low Power Mode and Android Battery Saver reduce background work and
  can stretch the time between updates. Turn them off (or plug in) for
  active driving.
* A phone reboot resets some background grants. Re-open the app and
  confirm the last-seen timestamp updates.

## Proof upload failed

**A photo, signature, or scan won't attach.**

* On iOS, proof capture is online. Retry on a stronger signal or Wi-Fi.
* On Android, proof capture queues offline — the capture should always
  attach to the local artifact even when offline, and upload happens once
  you reconnect. If the upload appears stuck:
  * Pull to refresh the task group.
  * Check the offline banner at the top of the app — if it still shows
    pending changes after you're back online for a few minutes, the queue
    may have hit a retry-able error.
  * As a workaround, you can re-capture the artifact. The duplicate is
    benign on the dispatcher side; they'll see two versions.

**Scanner won't recognize a barcode.**

* Better lighting, steadier framing. Glossy and damaged labels are the
  usual culprits.
* If the label genuinely won't scan, capture a **photo** of it instead
  (the photo artifact accepts any image) and message dispatch with the
  decoded value typed out.

## Can't open the camera

* Camera permission is denied. iOS: **Settings app** > **chrt** >
  **Camera**. Android: long-press the app icon > **App info** >
  **Permissions** > **Camera**.
* If the camera previews briefly and then black-screens, restart the app.
  If that doesn't help, restart the phone.

## App battery use is high

Live location streaming uses GPS, which costs battery. Expected behaviors:

* The blue location indicator in the iOS status bar shows when the app
  is using background location. This is normal during an active task
  group.
* Streaming + active screen + weak cell signal (the phone working harder
  to keep a connection) is the highest-drain combination.

To reduce drain:

* Toggle **Share Location with Dispatch** off when you're off shift.
* Don't force-quit and re-open the app constantly — the first GPS lock
  after a cold start is the most expensive operation. Background instead
  of swipe-away.
* Plug in for long drives.

If the app drains battery when **no task group is in progress** and
sharing is off, contact [hi@chrt.com](mailto:hi@chrt.com) — that's not
expected behavior.

## Offline banner won't clear (Android)

The banner shows **Syncing N pending changes…** indefinitely.

* Confirm you have a real internet connection (not just Wi-Fi without
  upstream).
* Force-close and reopen the app. The sync engine retries on app start.
* If the banner persists for more than a few minutes on solid signal,
  message dispatch — there may be a server-side error on a specific
  queued operation. Provide the order ID(s) you were working when the
  queue started piling up.

## Notifications missing

* Settings > **Push Notifications** card — does it say **Allowed**? If
  not, tap **Settings** to re-grant at the OS level.
* Settings > **Notification Preferences** card — are the event types
  you want enabled per channel?
* Some orgs configure dispatcher-side notifications instead of
  driver-side. Confirm with your dispatcher that you should be receiving
  alerts for the events you're missing.
* If the iOS lock-screen has a chrt notification, but the in-app badge
  doesn't update, pull to refresh — push delivery and in-app state can
  fall out of sync briefly.

## App is stuck on the splash screen

* Pull-down to force a refresh, or force-close and reopen.
* The app does a force-update check on start — if your version is too
  old, it shows a **Force Update** screen instead of the splash. Install
  the latest version from the App Store or Play Store.
* The app also enforces a maintenance lockout if chrt is in scheduled
  maintenance. The screen tells you what's going on — wait for the
  maintenance window to end.

## When to contact support

Include in your message:

* Your app version + build (from **Settings** > **Build Information**).
* Your phone model and OS version.
* The order ID(s) involved, if applicable.
* A screenshot of the error state if you can capture one.

Send to your dispatcher first, then [hi@chrt.com](mailto:hi@chrt.com) if
they can't resolve it.

## Related guides

* [Settings](/app/settings) — permissions and notification preferences.
* [Live location](/app/location) — how location sharing works end to
  end.
* [Proof of delivery](/app/proof-of-delivery) — capture flows and the
  Android offline queue.
* [Install the driver app](/app/install) — reinstall and first-launch
  permissions.