Troubleshooting — Error Codes & Common Messages

This article lists common errors users or support teams may see, explains likely causes, and gives recommended next steps.

“Mapbox token invalid / unauthorized”

Meaning: Mapbox access token missing, invalid or expired.

Cause: Tenant Mapbox token misconfigured or demo token rate-limited.

Remediation

• Verify tenant Mapbox token in Settings → Integrations → Mapbox Configuration. Use a per-tenant public token for production. :contentReference[oaicite:13]{index=13}
• Check browser console for exact Mapbox error and share with support.

“Geocoding failed” / property saved without coordinates

Meaning: Address geocoding attempt timed out or failed; property was saved but without lat/lng.

Cause: Mapbox geocoding API timed out or returned an error. The Property dialog calls a server-side mapbox-geocode function. :contentReference[oaicite:14]{index=14}

Remediation

• Retry geocoding from the property edit UI or check server logs for the mapbox-geocode function. If geocoding consistently fails, check Mapbox token and rate limits.

“Not authenticated” or “Not authenticated: Not authenticated”

Meaning: The client attempted an authenticated API call without a valid user session.

Cause: Session expired, user not signed in, or token invalid. Many components call supabase.auth.getUser() and expect an authenticated user. :contentReference[oaicite:15]{index=15}

Remediation

• Sign out and sign in again; confirm SSO/identity provider health if applicable. If session reauth fails, check backend auth logs.

“Upload failed” / image upload errors

Meaning: Photo or attachment failed to be uploaded to the server.

Cause: Network interruption, request timeouts for large files, or server rejection.

Remediation

• Retry upload on a stable connection (prefer Wi-Fi for bulk or large photos). Confirm the app shows whether items are queued for upload. See offline queue notes. :contentReference[oaicite:16]{index=16}

“Payment sync failed” or missing payment after reconnect

Meaning: Payment was recorded locally but failed to sync to server.

Cause: Offline/queue sync failure or server error during payment insertion.

Remediation

• Confirm the device reconnected and inspect client sync logs. Check the Payments page for deposit handling; deposits linked to estimates are treated specially. :contentReference[oaicite:17]{index=17}

Generic server 4xx/5xx errors

Meaning: A server-side validation (4xx) or runtime (5xx) error occurred.

Remediation

• Capture the request payload and server response. For 4xx errors, validate the fields sent (required fields, data types). For 5xx errors, collect server logs and escalate to the engineering team with a reproduction case.

Unknown error with stacktrace

Action

1. Note the exact error and stacktrace.
2. Capture reproduction steps and any recent related activity (e.g., property creation, large photo upload).
3. Attach logs and open a support ticket (see Support Process).

Updated on: 10/01/2026