Troubleshooting — Common Issues

This page lists the most frequent problems users see and concise steps to diagnose and remediate them.

Map not loading

Symptoms: Blank map, map tiles error, or “Mapbox” errors in the console.

Quick checks

1. Confirm the tenant has a configured Mapbox public token: Settings → Integrations → Mapbox Configuration. If no tenant token is configured the app uses a shared demo token with rate limits (suitable only for testing). :contentReference[oaicite:0]{index=0}
2. Open the browser console for authentication or token errors (token missing/invalid). The Jobs Map doc suggests checking the console for token errors. :contentReference[oaicite:1]{index=1}
3. If the demo token is used and you see rate-limit errors, configure a per-tenant token for production use. :contentReference[oaicite:2]{index=2}

If still failing: Capture console/network logs and provide them to your admin/dev team (see Logs & Diagnostics article).

Jobs not appearing on map or list

Symptoms: Jobs missing from the Jobs Map or Jobs list.

Quick checks

1. Verify date range and status filters — jobs may be filtered out. The Jobs Map UI supports date and status filters. :contentReference[oaicite:3]{index=3}
2. Ensure jobs have valid addresses or lat/lng coordinates; jobs without valid geolocation won’t appear on the map.
3. For technician assignment/visibility check role permissions — some views are scoped by role.

If still failing: Check the job record for address fields and coordinates; check server-side geocoding logs if address geocoding is expected.

Technician location not showing

Symptoms: Technician does not appear on Jobs Map.

Quick checks

1. Confirm the technician is clocked in — technicians must be clocked in to appear on the Jobs Map. :contentReference[oaicite:4]{index=4}
2. Confirm the device granted location permissions and that location services are enabled. See Permissions & Location docs for platform details.
3. Check device battery/battery-optimizer settings — some devices block background location updates; instruct technicians to whitelist the app for background activity if continuous tracking is required.

Note: The Jobs Map updates technician locations every ~15 seconds and job data every ~30 seconds. Intermittent connectivity will cause short delays. :contentReference[oaicite:5]{index=5}

Photos failing to upload or missing from Portfolio

Symptoms: Photo upload errors, missing photos in Job Portfolio.

Quick checks

1. If the device was offline when the photo was taken, photos are queued and uploaded when connectivity returns — confirm the device reconnected and the app synced. CJH queues photo uploads and other operations in IndexedDB. :contentReference[oaicite:6]{index=6}
2. For large photo batches prefer Wi-Fi to avoid cellular timeouts.
3. Confirm the photo was attached to the correct job/property — Portfolio aggregates photos by job and property address. Search Portfolio by job #, title, client, or address. :contentReference[oaicite:7]{index=7}

Payments / deposits not appearing

Symptoms: A payment recorded in the field does not appear in the Payments list.

Quick checks

1. Confirm the device reconnected — payments recorded offline are queued and sync on reconnect. :contentReference[oaicite:8]{index=8}
2. Confirm whether the payment was recorded as a deposit (estimate-linked) — the Payments screen treats estimate deposits specially and links them to the estimate. :contentReference[oaicite:9]{index=9}
3. If the payment shows locally but not on the server, capture the app sync diagnostics and server logs.

PWA install issues (desktop or mobile)

Symptoms: Install button missing, PWA not installable.

Quick checks

1. Confirm browser supports PWA installability (modern Chrome, Edge, Safari; behavior varies). The README notes the install button and Add to Home Screen flow. :contentReference[oaicite:10]{index=10}
2. Try a hard refresh or open the app in an incognito window to avoid service worker cache issues.

Push notifications not received

Symptoms: Users do not receive assignment or update notifications.

Quick checks

1. Confirm device notification permission is granted.
2. Confirm tenant-level push configuration (provider credentials) is set up.
3. Inspect server logs for push delivery errors. Push implementation is platform-dependent; if using PWA on iOS push may be limited — native apps tend to be more reliable for push. :contentReference[oaicite:11]{index=11}

Sign-in / authentication problems

Symptoms: “Not authenticated” errors, inability to sign in, or unexpected sign-outs.

Quick checks

1. Ensure correct credentials or SSO details. Many components check authentication via supabase.auth.getUser() and will throw a “Not authenticated” error if the session is invalid. See PropertyDialog and other components. :contentReference[oaicite:12]{index=12}
2. Clear site cookies and local storage, re-login, and verify network connectivity.

When to escalate

Updated on: 10/01/2026