Nightly Logo

New backend for storage.local API

To help improve Firefox performance, the backend for the storage.local API is migrating from JSON to IndexedDB. These changes will soon be enabled on Firefox Nightly and will stabilize when Firefox 63 lands in the Beta channel. If your users switch between Firefox channels using the same profile during this time, they may experience data regression in the extensions they have previously installed.

We recommend that users do not change Firefox channels between now and September 5, 2018. However, if they do and they contact you with questions about why their extensions are not behaving normally (such as losing saved options or other local data), please point them to this post for instructions on how to retrieve and re-import their extension data.

How to retrieve migrated data and re-import the extension data

Go to about:config and check the setting for extensions.webextensions.ExtensionStorageIDB.enabled. If it is set to true, the extension data has been moved to the new backend and is not directly available as a single file in the file system.

If the extension data is not available after it has been moved in the new backend, follow these steps to ask Firefox to re-import the extension data:

  1. Look up the Extension ID by going to about:debugging
  2. Navigate to your system profile directory
  3. Go to the folder called browser-extension-data
  4. Go to the folder of the Extension ID you found in about:debugging
  5. You will see a file named storage.js.migrated (or storage.js.migrated.N if the data has migrated more than once). Your data has been moved into this file.
  6. Uninstall the extension
  7. Copy the file named storage.js.migrated to a new file named storage.js in the same directory
  8. Open the browser console.
    1. You can access the browser console by going to the from [hamburger menu] → Web Developer → browser console
  9. Re-install the extension
  10. Wait for a message “Migrating storage.local data for <Extension debug name>” and “storage.local data successfully migrated to IDB Backend for <Extension debug name>” to appear in the browser console

How to address errors when re-importing migrated extension data

If you see a QuotaExceededError in the browser console during the final step in the data retrieval and re-importing process, you may have insufficient disk space. After you free  additional disk space, you maybe be able to fix this issue by following the steps outlined in the section above.

If the problem persists and the extension is using the new ExtensionStorageIDB backend, please report the issue on Bugzilla. You can see if the extension is using the ExtensionStorageIDB backend by going to about:config and seeing if extensions.webextensions.ExtensionStorageIDB.migrated.EXTENSION_ID is set to true.

Reporting issues with the storage.local API

If you are an extension developer and you encounter any issues that seem to be related to the storage.local API, please file a new issue on Bugzilla and add it as a blocker of bug 1474562 so that we can promptly investigate it.

8 comments on “New backend for storage.local API”

  1. Andrew wrote on

    What’s the reason for this?

    Is this part of Mozilla’s “Piss off add-on developers” plan? It sure seems like it.

    Reading the docs, it seems IndexedDB is more complex than storage.local.

    Please, please, please stop making me re-write my add-ons every few months! I have other things to do! I am not a full time add-on developer. I can only work on them in my spare time. I STILL haven’t finished porting my 16 add-ons to WebExtensions!


    1. Caitlin Neiman wrote on

      Hey Andrew! The backend migration will happen automatically — you won’t need to rewrite your extension if you use the storage.local API. 🙂

      The new backend will be able to provide more storage the current one. More information can be found here:

  2. t7yang wrote on

    six years long, the issue of indexedDB does not function in private mode (

    is this mean after ported to indexedDB, add-ons not going to able access storage data?

    1. Caitlin Neiman wrote on

      The IndexedDB database used for the storage.local backend is not tied to a window, so your extensions should still be able to access stored data when you are in private browsing. 🙂

    2. Juraj M wrote on

      In Private Browsing mode you can still access the IndexedDB through the background script (as a workaround).

  3. Juraj M wrote on

    Does this mean that we don’t have to use IndexedDB anymore and we can store everything in storage.local?

    Also how much more data will it hold without unlimitedStorage permission?

    1. Caitlin Neiman wrote on

      It depends on what kind of data you are trying to store. For example, you can’t store a Blob using the storage.local API, but you can store a Blob using the IndexedDB web API directly from an extension page.

      Currently, the unlimitedStorage permssion is not being used by either backend. Based on some local tests, it looks like the IDB backend is able to store more data than the JSONFile backend. How much data depends on how much free disk space is available. However, the new backend will raise a QuotaExceededError when the disk doesn’t have enough free space, whereas the JSONFile backend failed silently.

  4. Kulmegil wrote on

    I can no longer easily read or import extension data when creating new profile.
    It’s stored in a blob instead of nice json.
    As poweruser I really HATE the change.