[Bug]: storageState with opfs: [] cannot be restored in WebKit, and capturing OPFS there fails outright

[ayaangazali]

Version

1.63.0-next (reproduced on main at 46cd500; feature added in #42248)

Steps to reproduce

Two related problems with the new OPFS support. Both reproduce with the bundled test server.

1. A storage state carrying opfs: [] cannot be restored in WebKit.

const origin = 'http://localhost:PORT';
const withEmptyOpfs = { cookies: [], origins: [{ origin, localStorage: [{ name: 'k', value: 'v' }], opfs: [] }] };
const withoutOpfs   = { cookies: [], origins: [{ origin, localStorage: [{ name: 'k', value: 'v' }] }] };

await webkitBrowser.newContext({ storageState: withEmptyOpfs }); // throws
await webkitBrowser.newContext({ storageState: withoutOpfs });   // fine

2. storageState({ opfs: true }) throws on WebKit for every origin.

await webkitContext.storageState({ opfs: true });

Expected behavior

For 1, restoring an empty OPFS list is a no-op, so it should behave the same as omitting the field.
This matters because opfs: [] is what the other engines actually write. Capturing on Chromium and
reusing the file on WebKit is a normal workflow.

For 2, given the docs say "OPFS is currently not supported in ephemeral WebKit contexts"
(class-browsercontext.md:1594), capture should skip OPFS rather than fail the call.

Actual behavior

1. Identical states, differing only in that one field:

opfs: []    -> THREW: browser.newContext: Error setting storage state:
               Error: Unable to restore OPFS: The operation failed for an unknown transient reason (e.g. out of memory).
opfs absent -> OK, localStorage=v

And opfs: [] is exactly what the other engines produce for an origin with no OPFS files. Capturing
an origin that has localStorage but no OPFS gives:

browser=chromium originKeys=["origin","localStorage","indexedDB","opfs"] opfs=[]
browser=firefox  originKeys=["origin","localStorage","indexedDB","opfs"] opfs=[]

2. On WebKit:

Error: browserContext.storageState: Error: Unable to serialize OPFS:
The operation failed for an unknown transient reason (e.g. out of memory).

The whole call fails, including origins that never touched OPFS.

Additional context

For 1, the guard at packages/injected/src/storageScript.ts:226-237 looks like it already intends
the behaviour I would expect, but tests the wrong thing:

} catch (e) {
  // OPFS may be unavailable, e.g. on insecure origins or in WebKit contexts
  // that fail with 'unknown transient reason'. There is nothing to clear then,
  // so only fail when there are entries to restore.
  if (originState?.opfs === undefined)
    return;
  throw e;
}

The comment says "only fail when there are entries to restore", but the check is
=== undefined rather than emptiness, and opfs: [] has no entries. The protocol declares
opfs: array? (playwright.yml:353), so an empty array is a legal value distinct from an absent one.

For 2, collect() at storageScript.ts:183-189 wraps getDirectory() and rethrows as
Unable to serialize OPFS. On the server side the live-page loop swallows per-origin failures, but
the fallback blank-page loop in browserContext.ts has no equivalent catch, so it propagates. I am
less sure this one is unintended, since IndexedDB already threw the same way before this feature, so
treat it as the weaker of the two.

I have not opened a PR. My PRs here keep getting closed over an unsigned CLA on my side, so this is
more useful to you as a report. Happy to send a patch if that changes.

the second half is the part I would push back on myself, since it matches how IndexedDB already
behaved and may well be deliberate. the first one I am confident about, the comment and the code
disagree. freshman in college, thanks for reading :)

Environment

System:
  OS: macOS 26.5.2
  CPU: (10) arm64 Apple M4
Binaries:
  Node: 26.0.0
  npm: 11.12.1
npmPackages:
  playwright monorepo at main (1.63.0-next)

[TheSaiEaranti]

I have a fix and regression tests for empty OPFS restoration through newContext and setStorageState, preserving errors for nonempty data. Could you approve this scope for a community PR?

[ayaangazali]

Not mine to approve, that is for the maintainers, but for what it is worth the scope you describe sounds right to me and covering both newContext and setStorageState is a better catch than my report, since I only exercised the newContext path.

Scoping to the empty-restore half is also the call I would make. The two halves are not equally solid: the restore guard contradicts its own comment, so that one is clear cut, whereas the capture-side throw on WebKit mirrors how IndexedDB already behaved before this feature and may well be deliberate. I flagged that difference in the report and would not bundle them.

The repro that isolates it cleanly, in case it helps the regression test: build two storage states for the same origin differing only in that one field, and restore each in WebKit.

const withEmptyOpfs = { cookies: [], origins: [{ origin, localStorage: [{ name: 'k', value: 'v' }], opfs: [] }] };
const withoutOpfs   = { cookies: [], origins: [{ origin, localStorage: [{ name: 'k', value: 'v' }] }] };

opfs: [] throws Unable to restore OPFS, opfs absent succeeds. The reason it matters in practice
rather than only in theory is that opfs: [] is exactly what Chromium and Firefox write for an origin
that has other storage but no OPFS files, so a state captured on one engine and replayed on WebKit
fails. That round trip might be worth asserting directly.

Good luck with it, and thanks for picking it up.

[github-actions]

Hi, I'm the Playwright bot and I took a first look.

Confirmed by reading the source on main — the first half is a clear bug, the second is more likely working-as-intended. Your analysis lines up exactly with the code, so I'll be blunt about which is which.

1. opfs: [] cannot be restored in WebKit — real bug. In _restoreOPFS (packages/injected/src/storageScript.ts), when getDirectory() throws in an ephemeral WebKit context the guard is if (originState?.opfs === undefined) return; throw e;. The comment right above it says "only fail when there are entries to restore", but an empty array isn't undefined, so opfs: [] rethrows → Unable to restore OPFS. The protocol declares opfs: array? (playwright.yml:353), so [] is a legal value distinct from absent, and it's exactly what Chromium and Firefox write for an origin with other storage but no OPFS files — so a state captured on one engine and replayed on WebKit fails. Code and comment disagree; the fix is an emptiness check rather than === undefined.

2. storageState({ opfs: true }) throwing on WebKit — likely intended, agreeing with you. collect() rethrows getDirectory() failures as Unable to serialize OPFS. The live-page loop in browserContext.ts swallows per-origin failures, but the fallback blank-page loop (browserContext.ts:651-666) evaluates the collect script with no equivalent try/catch, so it propagates and fails the whole call. This mirrors how IndexedDB already behaved before OPFS existed, so I'd treat it as the weaker half and wouldn't bundle it with #1 either.

What I checked

• main (1.63.0-next, cited sha 46cd5008d), by source inspection — deps weren't installed in this environment, so I didn't run a live WebKit repro, but two people already have and the code matches the reports precisely.
• Restore guard: packages/injected/src/storageScript.ts _restoreOPFS — catch rethrows for any non-undefined opfs, including [].
• Capture propagation: packages/playwright-core/src/server/browserContext.ts:641-649 (live loop, catches) vs :651-666 (blank-page loop, no catch).
• Protocol: packages/protocol/spec/playwright.yml:353 — opfs: array?, so [] ≠ absent.
• Docs: docs/src/api/class-browsercontext.md — "OPFS is currently not supported in ephemeral WebKit contexts", which is why capture (fix(doc): npm run doc fixed #2) is defensible as-is.
• Reduced repro (matches the reporter's): two storage states for the same origin differing only in opfs, restored in WebKit — opfs: [] throws Unable to restore OPFS, opfs absent succeeds.

_{Triaged by the Playwright bot - agent run}