Firefox browser.storage.sync API Quota Limits

This article provides a breakdown of the storage quota limits imposed on web extensions using the browser.storage.sync API in the Firefox Web Browser. Developers must adhere to specific constraints regarding total storage capacity, individual item sizes, maximum item counts, and the frequency of write operations to ensure their extensions sync data reliably across a user's devices without triggering quota errors.

When developing a Firefox extension that synchronizes user settings or data via a Firefox Account, the browser.storage.sync API enforces strict limits. If an extension exceeds any of these quotas, the API call will fail, and the returned Promise will be rejected with an error.

Here are the exact storage and operational limits for browser.storage.sync in Firefox:

1. Total Storage Capacity

  • Property: browser.storage.sync.QUOTA_BYTES
  • Limit: 102,400 bytes (100 KB)
  • Details: This is the maximum total amount of data that an extension can store in the sync storage area. This calculation includes the size of the keys plus the JSON-stringified size of the values.

2. Individual Item Size

  • Property: browser.storage.sync.QUOTA_BYTES_PER_ITEM
  • Limit: 8,192 bytes (8 KB)
  • Details: No single item (a key-value pair) can exceed 8 KB. If you attempt to save an object or string that, combined with its key name, is larger than 8,192 bytes, the operation will be rejected even if you have plenty of total storage space remaining.

3. Maximum Number of Items

  • Property: browser.storage.sync.MAX_ITEMS
  • Limit: 512 items
  • Details: An extension can store a maximum of 512 separate key-value pairs in the sync storage area. To store more data points, developers must group multiple values into a single object under one key, while remaining mindful of the 8 KB per-item limit.

4. Write Operations Per Hour

  • Property: browser.storage.sync.MAX_WRITE_OPERATIONS_PER_HOUR
  • Limit: 1,800 operations
  • Details: An extension can perform up to 1,800 set(), remove(), or clear() operations within a single rolling hour.

5. Write Operations Per Minute

  • Property: browser.storage.sync.MAX_WRITE_OPERATIONS_PER_MINUTE
  • Limit: 120 operations
  • Details: To prevent extensions from overwhelming the sync server with rapid updates, Firefox limits extensions to 120 write operations per minute (an average of 2 operations per second).

Best Practices for Managing Quotas

Because browser.storage.sync is intended only for small amounts of data like user preferences, you should never use it for caching large datasets. If you need to store larger files, complex states, or make frequent write operations, use browser.storage.local instead, which offers a much larger default quota of 10 MB (and can be made unlimited with the unlimitedStorage permission) without rate-limiting write operations.