CNA-PLAT-011: Threaded Emscripten builds on the default WasmFS have no persistent storage, so StorageDevice refuses rather than saving

CNA snapshot c1c316b9  ·  Known Issues › Platform limitations  ·  source links pinned to c1c316b9

Threaded Emscripten builds default to WasmFS, which cannot link IDBFS, so StorageDevice there reports StorageDeviceNotConnectedException instead of persisting saves unless the application configures CNA_EMSCRIPTEN_USE_WASMFS=OFF.

Identifier

CNA-PLAT-011

Category

Platform limitation

Subsystem

Storage

Status

Narrowed (partially fixed; describes only what survives)

Verified against

CNA c1c316b9 (c1c316b9c7a846ce8002809c151fcd1af14942c9)

Evidence basis

Inferred (strong): follows from the code, but the behaviour was not run

Tests touching this area

None

Affected contract

StorageDevice/StorageContainer and LocalGamerServicesStore in threaded Emscripten builds

Expected behaviour

Save data should survive a reload of the page, as it survives a restart elsewhere.

Actual behaviour at TARGET

Since 8a67da536 and c5986156d the storage module links IDBFS. A pre-js hook (WebStoragePre.js) mounts /cna-storage and /save over IndexedDB with autoPersist and restores them before main(), and StorageDevice.cpp roots storage, and so the gamer-services store, there. CMakeLists.txt adds these link options only when NOT CNA_ENABLE_EMSCRIPTEN_THREADS OR NOT CNA_EMSCRIPTEN_USE_WASMFS. A threaded build on its default WasmFS therefore never sets Module.cnaStorageReady, and EnsureStorageRoot throws StorageDeviceNotConnectedException. A failed IndexedDB restore has the same result. Turning WasmFS off restores persistence, but the web limitations page warns that worker file access then waits on the browser thread.

Source locations

• modules/storage/src/WebStoragePre.js — IDBFS mounts of /cna-storage and /save, restored before main()
• modules/storage/CMakeLists.txt — links IDBFS only when NOT CNA_ENABLE_EMSCRIPTEN_THREADS OR NOT CNA_EMSCRIPTEN_USE_WASMFS
• modules/storage/src/StorageDevice.cpp — EnsureStorageRoot: the browser root, StorageDeviceNotConnectedException while cnaStorageReady is unset
• docs/web-emscripten-graphics-limitations.md — threaded builds: WasmFS by default; CNA_EMSCRIPTEN_USE_WASMFS=OFF for persistent storage

Evidence

Checked by grep and reading at c1c316b9; nothing was built for or run in a browser.

Re-verified at b0e97bb1: 8a67da536 (SAMPLE-070) and c5986156d (SAMPLE-071) added the IDBFS mounts and their link condition; read WebStoragePre.js, the storage CMakeLists.txt and StorageDevice.cpp. Not executed.

Focused reproduction

No focused reproduction is known. Nothing has been invented here; the evidence above is what exists.

Current tests

No automated browser storage test; CNA records a Chrome save/reload run of SAMPLE-070 in NEXT.md.

Regression test

A browser test of a threaded WasmFS build that writes, reloads and reads back, expecting either persistence or the documented refusal.

Blast radius

Threaded web builds on the default WasmFS that save games, settings or local achievements.

Workaround

Configure -DCNA_EMSCRIPTEN_USE_WASMFS=OFF in threaded builds that need saves.