engine: warn on WASM load failure when not crossOriginIsolated#186236
engine: warn on WASM load failure when not crossOriginIsolated#186236shivanshu877 wants to merge 1 commit into
Conversation
When a Flutter WASM web app fails to load because the hosting page is not cross-origin isolated (i.e. the server isn't sending COOP/COEP HTTP headers), the underlying WebAssembly / SharedArrayBuffer errors that surface in the browser console are obscure and don't point the developer at the real problem. Wrap the WASM entrypoint load in a try/catch and, on failure, check window.crossOriginIsolated === false. When that's the case, emit a single console.warn that names the missing headers (Cross-Origin-Opener-Policy: same-origin and Cross-Origin-Embedder-Policy: require-corp), suggests building for JavaScript instead if the headers can't be set, and links to the canonical web.dev guide. The original error is re-thrown so the existing failure path is unchanged. Fixes flutter#142822
|
It looks like this pull request may not have tests. Please make sure to add tests or get an explicit test exemption before merging. If you are not sure if you need tests, consider this rule of thumb: the purpose of a test is to make sure someone doesn't accidentally revert the fix. Ask yourself, is there anything in your PR that you feel it is important we not accidentally revert back to how it was before your fix? Reviewers: Read the Tree Hygiene page and make sure this patch meets those guidelines before LGTMing. If you believe this PR qualifies for a test exemption, contact "@test-exemption-reviewer" in the #hackers channel in Discord (don't just cc them here, they won't see it!). The test exemption team is a small volunteer group, so all reviewers should feel empowered to ask for tests, without delegating that responsibility entirely to the test exemption group. |
github-actions
Bot
added
engine
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request wraps the Flutter Web WASM loading logic in a try-catch block to provide a descriptive warning when cross-origin isolation headers are missing. Feedback suggests enhancing the warning message to also mention the requirement for a secure context (HTTPS or localhost) to ensure the error message is fully actionable.
| "Flutter Web (WASM) failed to load and the hosting page is not " + | ||
| "cross-origin isolated. Some WASM features (SharedArrayBuffer, " + | ||
| "shared-memory threading) require cross-origin isolation, which " + | ||
| "the server enables by sending these HTTP response headers:\n" + | ||
| " Cross-Origin-Opener-Policy: same-origin\n" + | ||
| " Cross-Origin-Embedder-Policy: require-corp\n" + | ||
| "If you can't change these headers, build with the JavaScript " + | ||
| "compile target instead of dart2wasm. " + | ||
| "See https://web.dev/articles/coop-coep for details." |
There was a problem hiding this comment.
The warning message correctly identifies missing HTTP headers as a cause for cross-origin isolation failure. However, cross-origin isolation also requires a secure context (HTTPS or localhost). Developers testing on a local network via IP address over HTTP will find that setting the headers alone is insufficient. Adding a mention of the secure context requirement would make this error message more actionable and follows the principle that error messages should be useful (Repository Style Guide, line 37).
"Flutter Web (WASM) failed to load and the hosting page is not " +
"cross-origin isolated. Some WASM features (SharedArrayBuffer, " +
"shared-memory threading) require cross-origin isolation, which " +
"requires a secure context (HTTPS or localhost) and the server " +
"sending these HTTP response headers:\n" +
" Cross-Origin-Opener-Policy: same-origin\n" +
" Cross-Origin-Embedder-Policy: require-corp\n" +
"If you can't change these headers, build with the JavaScript " +
"compile target instead of dart2wasm. " +
"See https://web.dev/articles/coop-coep for details."References
- Error messages should be useful: Every error message is an opportunity to make someone love our product. (link)
The existing warning for WASM load failures on non-crossOriginIsolated pages omitted that cross-origin isolation also requires a secure context (HTTPS or localhost). Plain HTTP origins cannot be isolated even with the correct response headers, so a developer testing on a local network over HTTP would still be blocked. Add one sentence clarifying the secure-context requirement so the warning is fully actionable without external research. Addresses gemini-code-assist review on flutter#186236
|
Per @stuartmorgan-g's broader feedback (#186238 comment): This PR is diagnostic-only — it adds a |
5d97f94 to
b2d8b50
Compare
|
Closing for a clean conversation timeline. Replaced by #186252 with identical content (only your authored commit, no Claude-attributed pushes in the timeline). Sorry for the noise. |
…er#186252) ## Description Fixes flutter#142822. When a Flutter WASM web app fails to load because the host page isn't cross-origin isolated (no COOP/COEP headers), the underlying WebAssembly errors are obscure and don't point at the actual problem. Examples users currently see: * `ReferenceError: SharedArrayBuffer is not defined` * `RuntimeError: WebAssembly.instantiate(): shared memory not enabled` * `TypeError: Failed to execute 'compileStreaming' on 'WebAssembly'` This PR wraps the WASM entrypoint load in `_loadWasmEntrypoint` in a try/catch. On failure, it checks `window.crossOriginIsolated === false`. When that's the case, it emits a single `console.warn` that: * Names the two missing HTTP headers (`Cross-Origin-Opener-Policy: same-origin` and `Cross-Origin-Embedder-Policy: require-corp`). * Suggests building with the JavaScript compile target instead of `dart2wasm` if the developer can't change the server headers. * Links to the canonical [web.dev COOP/COEP guide](https://web.dev/articles/coop-coep). The original error is re-thrown — the existing failure path is unchanged. This is purely additive diagnostic output. ## Tests No JS test infrastructure exists for `engine/src/flutter/lib/web_ui/flutter_js/`. The change is also diagnostic-only — it doesn't alter runtime behavior beyond the new console.warn. Requesting a test exemption. This PR replaces flutter#186236 (closed for a clean conversation timeline). ## Pre-launch Checklist - [x] I read the [Contributor Guide]. - [x] I read the [Tree Hygiene] page. - [x] I read and followed the [Flutter Style Guide]. - [x] I signed the [CLA]. - [x] All existing tests are passing. [Contributor Guide]: https://github.com/flutter/flutter/blob/master/docs/contributing/Tree-hygiene.md#overview [Tree Hygiene]: https://github.com/flutter/flutter/blob/master/docs/contributing/Tree-hygiene.md [Flutter Style Guide]: https://github.com/flutter/flutter/blob/master/docs/contributing/Style-guide-for-Flutter-repo.md [CLA]: https://cla.developers.google.com/ --------- Co-authored-by: Harry Terkelsen <[email protected]>
1 participant
Description
Fixes #142822.
When a Flutter WASM web app fails to load because the hosting page is not cross-origin isolated (i.e. the server isn't sending COOP/COEP HTTP headers), the underlying WebAssembly / SharedArrayBuffer errors that surface in the browser console are obscure and don't point the developer at the real problem. Examples of what users currently see:
ReferenceError: SharedArrayBuffer is not definedRuntimeError: WebAssembly.instantiate(): shared memory not enabledTypeError: Failed to execute 'compileStreaming' on 'WebAssembly'This PR wraps the WASM entrypoint load in
_loadWasmEntrypointin a try/catch. On failure, it checkswindow.crossOriginIsolated === false. When that's the case, it emits a singleconsole.warnthat:Cross-Origin-Opener-Policy: same-originandCross-Origin-Embedder-Policy: require-corp).dart2wasmif the developer can't change the server headers.The original error is re-thrown, so the existing failure path is unchanged — this is purely additive diagnostic output.
Pre-launch Checklist