Clarifying SecurityError in StorageManager.getDirectory

[mpsuzuki]

---

Description

Add concrete examples of the error in OPFS getDirectory() method, at StorageManager.getDirectory#Exceptions

Motivation

Currently, the documentation states:

SecurityError DOMException
  Thrown if the user agent is not able to map the requested directory to the local OPFS.

I propose adding concrete scenarios that cause this exception, as the lack of detail may lead to confusion for developers implementing OPFS-based storage, like:

SecurityError DOMException
  Thrown if the user agent is not able to map the requested directory to the local OPFS, due to factors such as:
    * Storage or memory constraints that prevent OPFS allocation.
    * Security policies, including restrictions in non-secure contexts (e.g., non-HTTPS sessions).
    * Private browsing mode, where OPFS access is commonly restricted by browsers to prevent persistent data storage.

Additional details

SQLite developers have specifically highlighted OPFS limitations in Incognito and Guest modes in their documentation: Achtung: Restrictions in Incognito and Guest Browsing Modes.

In real-world tests, both Firefox and Safari threw a SecurityError when calling getDirectory() inside Private Browsing mode:

Firefox 128.11.0 error: "Security error when calling GetDirectory"

Safari 17.6 error: "UnknownError: The operation failed for an unknown transient reason (e.g. out of memory)"

While browsers intentionally obscure Private Browsing detection, a small note in MDN can help developers anticipate storage failures in such contexts without directly exposing detection mechanisms.

Would it be possible to add a small clarification about these known limitations to better support developers encountering this issue?

Related issues and pull requests

[github-actions]

Preview URLs

• /en-US/docs/Web/API/StorageManager/getDirectory

(comment last updated: 2025-06-18 15:15:59)

[wbamberg]

Thanks for your PR. I had a couple of questions about some of the cases you have listed.

Also, do you have any references from the specification about when these errors are expected to be raised?

[wbamberg]

Does this mean that the API doesn't work in private browsing mode? Our documentation on storage quotas and persistence (https://developer.mozilla.org/en-US/docs/Web/API/Storage_API/Storage_quotas_and_eviction_criteria#private_browsing) says that in PB mode data is not persisted after the session ends, but not that the API is itself disabled. Do you have a test case where we can try this out?

[mpsuzuki]

My testcase was found during my experiments with SQLite3 WASM, https://gitlab.com/mpsuzuki/test-sqlite3-wasm. I would update this repository by this weekend, to add local https servers for test.

In my experiment, the Private Browsing mode on Google Chrome and Microsoft Edge allow the clients to write something to OPFS. On the other hand, the Private Browsing mode on Firefox and Apple Safari disallow the clients to write anything on OPFS.

[wbamberg]

It looks to me like, yes, Firefox throws when you call this method in PB mode. But in Safari, it looks like navigator.storage is just unavailable:

So I'm not seeing this (from https://gitlab.com/mpsuzuki/test-sqlite3-wasm#known-limitations):

For example, in the Private Browsing mode, ...Apple Safari returns "Unhandled Promise Rejection: UnknownError: The operation failed for an unknown transient reason (e.g. out of memory)".

[wbamberg]

Ideally we document browser-specific behavior in the browser compatibility table, so we could have a note attached to the Firefox entry for getDirectory saying something like "Throws a SecurityError in private browsing mode".

[mpsuzuki]

Listing the failures & errors in each browser is ideal, I fully agree, but I'm afraid it is too version-specific and the maintenance can be heavy task.

For example, my Safari 18.5 running on Ventura (macOS 13.7.6) shows the errors like below for my test case. The screenshot is taken by Japanese language environment (I'm sorry), "プライベート" means "private", "バージョン" means "version". navigator.storage is available under the Private Browsing mode. Which version of your Safari?

[mpsuzuki]

Just I've updated my testkit test-sqlite3-wasm, HTTPS & HTTP servers are added.

[wbamberg]

Yes, I can confirm that I get an error on Safari 18.4. But it's not a SecurityError, it's UnknownError:

It is a SecurityError in Firefox.

[mpsuzuki]

@wbamberg , please could you tell me about the tasks unresolved in my side?

[wbamberg]

👍 thank you!

[mpsuzuki]

Thank you!