Sync Troubleshooting — Diagnose and fix sync failures

This article helps support and end users diagnose and resolve synchronization problems when queued items fail to upload or reconcile.

Quick checklist — common causes

1. No network connectivity — The device is still offline or has flaky connectivity. Confirm network access.
2. Server errors — The server returned an error (validation, auth, or runtime); the client should show the error in logs or UI.
3. Authentication/session issues — The user session expired and the client cannot authenticate API calls (e.g., Not authenticated). Many components call supabase.auth.getUser() and will fail if the session is invalid; sign out and sign back in to refresh the session. :contentReference[oaicite:8]{index=8}
4. Large file/timeouts — Large photo uploads or slow networks can cause timeouts. Use Wi-Fi or retry later.
5. Conflict rejections — Server rejects an update because of version mismatch or business rule.

Step-by-step diagnosis

1. Check the client UI for queued items — The app should indicate items awaiting sync (jobs, photos, payments). Confirm which items are still queued.
2. Confirm network — Switch to Wi-Fi and retry sync. For intermittent cellular issues, a stable Wi-Fi connection often resolves large upload failures. :contentReference[oaicite:9]{index=9}
3. Check authentication — If the client reports authentication errors, sign out and sign in again.
4. Capture logs — If the problem persists, collect client logs and HAR/network captures (see Logs & Diagnostics). For mobile native apps, capture adb logcat (Android) or Xcode device logs (iOS).
5. Examine server responses — Look at the server response for failing requests. If a validation error is returned, check the outgoing payload for missing or malformed fields.
6. Retry or re-create — If a queued update repeatedly fails (e.g., due to a persistent server validation), consider copying the content, deleting the queued item locally, and re-submitting it following any needed corrections.

Recovering from common cases

• Photos stuck in queue: Ensure the app has network + sufficient local resources; try uploading a single photo while observing the network logs. Use Wi-Fi for large batches. :contentReference[oaicite:10]{index=10}
• Payments not syncing: Confirm the payment record was created properly, then check sync logs. If a server validation failed, capture the exact server response for support. Payments recorded offline will sync on reconnect. :contentReference[oaicite:11]{index=11}
• Job update conflicts: Open the current server record and compare fields. If a conflict was detected, follow the process in “Conflict Resolution”.

When to escalate

If you cannot resolve the sync failure after the above steps, gather the recommended diagnostic artifacts (console/HAR, IndexedDB export, mobile logs) and open a ticket with Support (see Logs & Diagnostics and Support Process). Include timestamps and copies of queued entries for faster diagnosis.

Tip: For frequent or systematic failures, instrument the sync path to log request IDs and server error details so engineering can identify root causes quickly.

Updated on: 10/01/2026