useHtmlRenderObject() doesn't catch engine surface-creation failures, crashing all SVG widgets on Flutter web / CanvasKit
Minimal reproducible example.
flutter run -d chrome(or any browser), tap Open Intro — the firstSvgPicturebuild crashes its subtree. Reproduces on Flutter 3.44.6 (latest stable) with vector_graphics 1.2.2 (latest), and on Flutter 3.38.5 (the production version).
vector_graphics' useHtmlRenderObject() probes renderer capabilities with
picture.toImageSync(1, 1) and catches UnsupportedError, StateError, and
NoSuchMethodError. When WebGL surface creation fails and the engine's
software-surface fallback also fails, what toImageSync throws is none of
those — and it is engine-version-dependent:
- Flutter 3.38.x:
Surface._makeSoftwareCanvasSurfacewraps the failure intoCanvasKitError('Failed to create CPU-based surface: ...'). - Flutter 3.44.x: the refactored engine (
_recreateSoftwareSkSurface) has no such wrapper, so CanvasKit's bare JS string ("Canvas with id ... was not found") propagates as-is — it is not even a DartError.
Either way the value escapes the probe and crashes the VectorGraphic
widget build. Because _cachedUseHtmlRenderObject is only cached on success,
every subsequent SVG build repeats the crash.
In production (details below) this happens organically on Safari/WebKit. This MRE simulates the same engine state deterministically so it reproduces in any browser — see Simulation fidelity.
flutter pub getflutter run -d chrome(any browser/mode works; the trigger is simulated inweb/index.html)- On the Splash screen tap Open Intro. The tap arms the simulated WebGL
failure (mirroring the mid-session environmental failure seen in
production), then navigation builds the first
SvgPicture.
The Splash screen (PNG background) renders normally, and the app chrome (progress bars, buttons) keeps rendering after the crash — only SVG widgets die. This matches production sessions, where the display surface kept working.
Same as the StateError / NoSuchMethodError cases fixed in 1.2.1
(flutter/packages#11685): the probe treats the failure
as "raster path unavailable" and falls back to the HTML compatibility render
object.
Flutter 3.44.6 / vector_graphics 1.2.2 — the escaping value is a bare JS string (note the framework header says "message", not an error type):
══╡ EXCEPTION CAUGHT BY WIDGETS LIBRARY ╞═══════════════════════════════════════════════════════════
The following message was thrown building VectorGraphic(dirty, dependencies: [Directionality,
_LocalizationsScope-[GlobalKey#31715]], state: _VectorGraphicWidgetState#febb2):
Canvas with id [object OffscreenCanvas] was not found
The relevant error-causing widget was:
VectorGraphic
VectorGraphic:file:///.../vector_graphics-1.2.2/lib/src/vector_graphics.dart:76:24
════════════════════════════════════════════════════════════════════════════════════════════════════
Another exception was thrown: Canvas with id [object OffscreenCanvas] was not found
Another exception was thrown: Canvas with id [object OffscreenCanvas] was not found
Flutter 3.38.5 / vector_graphics 1.2.2 — same scenario, engine wraps it
into CanvasKitError:
══╡ EXCEPTION CAUGHT BY WIDGETS LIBRARY ╞═══════════════════════════════════════════════════════════
The following CanvasKitError was thrown building VectorGraphic(dirty, dependencies: [Directionality,
_LocalizationsScope-[GlobalKey#ddb88]], state: _VectorGraphicWidgetState#8d3d3):
Failed to create CPU-based surface: Canvas with id [object OffscreenCanvas] was not found.
When the exception was thrown, this was the stack:
lib/_engine/engine/canvaskit/surface.dart 474:7 [_makeSoftwareCanvasSurface]
lib/_engine/engine/canvaskit/surface.dart 448:16 [_createNewSurface]
lib/_engine/engine/canvaskit/surface.dart 278:23 createOrUpdateSurface
lib/_engine/engine/canvaskit/picture.dart 94:40 toImageSync
package:vector_graphics/src/render_object_selection.dart 28:20 useHtmlRenderObject
package:vector_graphics/src/vector_graphics.dart 458:40 get _webRenderObject
package:vector_graphics/src/vector_graphics.dart 487:11 build
════════════════════════════════════════════════════════════════════════════════════════════════════
Another exception was thrown: CanvasKitError: Failed to create CPU-based surface: Canvas with id [object OffscreenCanvas] was not found.
(In this MRE run in Chrome the engine uses an OffscreenCanvas, hence
[object OffscreenCanvas]; on production Safari the same code path reports
[object HTMLCanvasElement].)
The production trigger — WebGL surface creation failing mid-session on
Safari — is environmental and cannot be reproduced on demand. The script in
web/index.html recreates the engine state observed in
production telemetry, verified against the engine source of both versions.
It stays dormant until the first pointerdown, so the app boots and renders
normally; once armed:
- New WebGL surface creation fails:
MakeOnScreenGLSurfacereturnsnull. Already-created surfaces (the display surface) keep working — matching production sessions, where the app had rendered and navigated several routes before the crash. - The engine's software fallback also fails:
MakeSWCanvasSurfacethrows"Canvas with id <canvas> was not found"— verbatim what CanvasKit'sMakeSWCanvasSurfacethrows on production Safari when itsinstanceof HTMLCanvasElementcheck fails for the engine's own canvas element (which nevertheless stringifies as[object HTMLCanvasElement]).
From Picture.toImageSync onward, everything is the real engine and the real
package code.
Since 2026-04-20: ~1,130 events, ~110 users, essentially all on Safari/WebKit (Mobile Safari 16.6–26.5, Mobile Safari WKWebView, desktop Safari; a single Firefox event out of >1,000). Flutter 3.38.5 web app (CanvasKit renderer, dart2js release build) embedded in an iframe on a partner page. Production stack (release build, Sentry):
CanvasKitError: Failed to create CPU-based surface: Canvas with id [object HTMLCanvasElement] was not found.
org-dartlang-sdk:///lib/_engine/engine/canvaskit/surface.dart:474 Surface._makeSoftwareCanvasSurface
org-dartlang-sdk:///lib/_engine/engine/canvaskit/surface.dart:278 Surface.createOrUpdateSurface
org-dartlang-sdk:///lib/_engine/engine/canvaskit/picture.dart:94 CkPicture.toImageSync
vector_graphics-1.1.19/lib/src/render_object_selection.dart:28 useHtmlRenderObject
vector_graphics-1.1.19/lib/src/vector_graphics.dart:464 _VectorGraphicWidgetState.build
The probe exists to answer one question — "can toImageSync be used?" — and
any throw answers "no". Enumerating engine failure types has proven to be a
losing game: UnsupportedError (old HTML renderer), StateError /
NoSuchMethodError (iOS 18.7, fixed in 1.2.1 /
flutter/packages#11685), CanvasKitError (≤3.38,
engine-internal and unimportable), and now a bare JS string (≥3.44, not even
a Dart Error). Suggest replacing the type-specific clauses in
useHtmlRenderObject() with a catch-all:
try {
image = picture.toImageSync(1, 1);
_cachedUseHtmlRenderObject = false;
} on Object catch (_) {
// If toImageSync fails for any reason (the failure type varies by engine
// version and renderer), the raster path is unusable — fall back to the
// HTML compatibility render object.
_cachedUseHtmlRenderObject = true;
} finally {
...
}- Reproduced on Flutter 3.44.6 (stable, ee80f08bbf) • Dart 3.12.2 and
Flutter 3.38.5 (stable, f6ff1529fd) • Dart 3.10.4 (
.fvmrcpins 3.44.6) - vector_graphics 1.2.2 (latest; also observed on 1.1.19 in production) via flutter_svg 2.2.3
- Reproduces in any browser with the simulation; occurs organically on Safari/WebKit in production