fix(webgl): explain WebGL2-context failures with a troubleshooting hint#251
Merged
Conversation
When the browser/Electron webview cannot create a WebGL2 context, niivue throws "unable to get WebGL context. Maybe the browser doesn't support WebGL2." which already surfaces in the on-canvas error panel. On its own that message reads like a corrupt file, when it is actually an environment issue (no hardware acceleration, e.g. the VS Code snap build, missing GPU drivers, or recent Chromium dropping the automatic SwiftShader fallback). - Volume error panel: when the message is exactly that WebGL2-context error, append a short note clarifying it is an environment issue (not the file) plus a "How to fix" link to issue #236. Every app that mounts the shared viewer inherits this. - VS Code README: add a Troubleshooting section with the recommended fix (restore hardware acceleration) and the temporary enable-unsafe-swiftshader workaround. Refs #236 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Contributor
🚀 PWA Preview DeploymentYour PWA preview has been deployed! Preview URL: https://niivue.github.io/niivue-vscode/pr-251/ This preview will be updated automatically when you push new commits to this PR. |
Contributor
Coverage ReportOverall line coverage: 42.1%
|
Contributor
🧹 PWA Preview CleanupThe preview deployment for this PR has been removed. |
korbinian90
added a commit
that referenced
this pull request
Jun 19, 2026
Reconcile #250 (brand menu + NVDocument Save/Load split button) and #251 (WebGL2 context-error hint) with the v1.0 core migration. Resolution (Menu.tsx conflicts + the auto-merged document path, kept on the v1 API): - Keep #250's "NVDocument" Save/Load split button, but Save uses nv.serializeDocument() (v1 CBOR), not the removed nv.json(). The dropdown becomes Save / Save as JSON / Load, combining #250's Load entry with the migration's JSON export. - events.ts and Volume.tsx auto-merged; #250's loadDocumentEvent coexists with the v1 ExtendedNiivue, loaders, and event wiring. - Migrate #250's new MenuBrandDocument.test.tsx to the v1 niivue surface (default NiiVueGPU export, serializeDocument, header-based metadata) and add a Save-as-JSON assertion. turbo type-check 8/8; @niivue/react 157 unit tests pass; react + pwa build. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
The on-canvas error panel now adds a short, targeted explanation and a "How to fix" link when WebGL2 context creation fails, instead of showing only niivue's raw message. Also adds a Troubleshooting section to the VS Code extension README.
Refs #236.
Why
Reported on Linux in VS Code and reproduced on a second Debian machine: the same extension version that works on Windows fails with "Failed to load image: unable to get WebGL context. Maybe the browser doesn't support WebGL2."
The cause is environmental, not a bug in the extension. Recent Chromium (context creation starts failing around Chromium 144, which reached users via the VS Code Electron bump) removed the automatic fallback to software WebGL (SwiftShader). When the webview has no working hardware WebGL2 (common with the snap build of VS Code, missing or blocklisted GPU drivers, or some Wayland setups),
getContext('webgl2')returns null. Windows is unaffected because its software fallback is Direct3D WARP, which Chromium does not gate.niivue's message already surfaced in the error panel, but on its own it reads like a corrupt file. This change keeps that message and appends one line clarifying it is an environment/GPU issue, with a pointer to the fix.
Changes
packages/niivue-react/src/components/Volume.tsx: in the existingnv.loadErrorpanel, when the message is exactlyunable to get WebGL context, render a concise note plus a "How to fix" link to WebGL2 context not working everywhere #236. Detection is a precise substring match. Every app mounts the sharedContainer->Volume, so the PWA, Jupyter, Streamlit, and desktop apps inherit it too.apps/vscode/README.md: Troubleshooting section with the recommended fix (restore hardware acceleration; replace the snap with the official.deb) and the temporaryenable-unsafe-swiftshaderargv.json workaround, flagged as temporary since Chromium is removing it.Notes for reviewers
prettier --writewas intentionally not run on the touched existing files (repo source is not Prettier-conformant at baseline), so the diff is intent-only.@niivue/reactandniivueunit tests, and lint all pass.🤖 Generated with Claude Code