Browser Storage & Offline-First State Persistence

Resolving QuotaExceededError: Browser Storage Limits Across Chrome, Firefox, and Safari

Problem Statement: Cross-Browser QuotaExceededError and Silent Data Loss

Offline-first applications frequently fail during bulk state synchronization or asset caching. Developers encounter QuotaExceededError (DOMException 22) or experience silent data truncation when writing to IndexedDB or the Cache API. The failure manifests inconsistently because Browser Storage Fundamentals & Quotas vary by engine implementation, device capacity, and user interaction state.

Common Symptoms:

Root Cause: Divergent Quota Management & Eviction Strategies

Each browser enforces distinct storage boundaries and lifecycle rules.

Engine-Specific Breakdown:

Understanding these mechanics is critical for implementing robust Storage Quotas & Eviction Policies.

Step-by-Step Fix: Quota-Aware Write Implementation

Implement a defensive write pipeline that checks available quota, requests persistence, and handles overflow gracefully before committing data to IndexedDB or Cache API.

  1. Query current usage and available quota Call navigator.storage.estimate() to retrieve usage and quota. Calculate remaining capacity before initiating bulk writes to prevent mid-transaction failures.

  2. Request persistent storage Invoke navigator.storage.persist() early in the app lifecycle. On Safari, this must be triggered directly from a user gesture (click/tap). Without persistence, data remains temporary and subject to automatic eviction.

  3. Wrap write operations in a quota-aware async handler Use try/catch blocks around database transactions. Implement chunked writes and fallback to in-memory buffers or compressed formats when approaching 80% of available capacity.

  4. Handle QuotaExceededError explicitly Catch DOMException with name === 'QuotaExceededError' or legacy code === 22. Trigger immediate cache/DB cleanup routines, log telemetry, and notify the user to free disk space or reduce sync frequency.

/**
 * Production-safe quota-aware write handler for IndexedDB.
 * Uses the native IDBDatabase API; no wrapper library required.
 */
async function safePersistData(db, storeName, payload) {
  const { usage = 0, quota = 0 } = await navigator.storage.estimate();
  const remaining = quota - usage;
  const payloadSize = new Blob([JSON.stringify(payload)]).size;

  // Proactive cleanup at 80% capacity threshold
  if (remaining > 0 && payloadSize > remaining * 0.8) {
    console.warn(
      '[Storage] Approaching quota limit. Initiating background cleanup.'
    );
    await clearOldEntries(db, storeName);
  }

  // Request persistent storage if not already granted
  if (navigator.storage.persist && !(await navigator.storage.persisted())) {
    const granted = await navigator.storage.persist();
    if (!granted) {
      console.warn(
        '[Storage] Persistent storage denied. Data subject to browser eviction.'
      );
    }
  }

  return new Promise((resolve, reject) => {
    const tx = db.transaction(storeName, 'readwrite');
    const store = tx.objectStore(storeName);

    store.put(payload, 'current_state');

    tx.oncomplete = async () => {
      const updated = await navigator.storage.estimate();
      resolve({ success: true, usage: updated.usage });
    };

    tx.onerror = () => {
      const err = tx.error;
      if (err && (err.name === 'QuotaExceededError' || err.code === 22)) {
        console.error(
          '[Storage] QuotaExceededError triggered. Executing emergency eviction.'
        );
        clearOldEntries(db, storeName).catch(console.error);
        reject(
          new Error(
            'Storage quota exceeded. Fallback cleanup executed. Retry with reduced payload.'
          )
        );
      } else {
        reject(err);
      }
    };
  });
}

async function clearOldEntries(db, storeName) {
  return new Promise((resolve, reject) => {
    const tx = db.transaction(storeName, 'readwrite');
    tx.objectStore(storeName).clear();
    tx.oncomplete = () => resolve();
    tx.onerror = () => reject(tx.error);
  });
}

Validation: Cross-Browser Quota Testing & Verification

Verify implementation stability by simulating low-disk conditions and monitoring quota reporting accuracy across target browsers.