Background Sync Not Running

Symptom	Likely cause	Fix
`registration.sync` is undefined	Browser does not support Background Sync	Use foreground retry fallback
Sync registered but does not fire	Browser heuristics, power, network, or engagement throttling	Retry when app opens and when online event fires
Periodic sync never runs	Experimental and browser-controlled	Do not use for critical behavior
Queue replays duplicates	Missing idempotency key	Use client mutation IDs and server idempotency
Queue gets stuck	Failed item blocks later items	Add attempts, error state, and manual resolve path
User thinks work is done	UI hides pending state	Show pending, failed, and synced status clearly

Fallback Pattern

window.addEventListener('online', () => {
  void replayOutboxInForeground();
});

document.addEventListener('visibilitychange', () => {
  if (document.visibilityState === 'visible') {
    void replayOutboxInForeground();
  }
});