Offline Sync Debugging
Start with the local queue. If you cannot explain what is pending, you cannot debug sync.
| Symptom | Check | Fix |
|---|---|---|
| mutation stuck pending | next_attempt_at, last_error, auth state | retry after auth refresh or surface user action |
| duplicate server rows | idempotency key missing or regenerated | persist stable key per local action |
| local state flips back | server rejected optimistic mutation | show correction and reason |
| conflict loop | client keeps replaying stale base version | require rebase or user conflict resolution |
| queue drains only in foreground | background sync unavailable/throttled | retry on app open and network regain |
| stale reads | pull cursor/version not advancing | log server version and local applied version |
Debug View
Every sync-capable app should have an internal debug view with:
- pending mutation count
- oldest pending mutation age
- last successful push/pull
- last error
- current local schema version
- current remote cursor/version
Retry Gate
Retries must be safe. Before enabling automatic retry, prove duplicate sends do not duplicate server state.