Skip to content

[tool][web] Intercept dart2wasm exit code 254 cleanly and provide JS interop migration guidance for Wasm & dry-runs #190466

Closed

Description

@kevmoo

Currently, when compiling a web project with flutter build web --wasm (or evaluating compat via dry-run) that encounters incompatible legacy JS interop dependencies (such as dart:html or package:js), the terminal output suffers from two usability defects:

  1. Uncaught ProcessException Dump (Standard Wasm Builds): flutter_tools invokes ProcessUtils.run(throwOnError: !compilerConfig.dryRun). Expected compiler failures (exit code 254) during standard --wasm builds are treated as unexpected tool exceptions, dumping a 2,000+ character compiler sub-command string and a 22-frame internal Dart tool stack trace (_DefaultProcessUtils.run, Dart2WasmTarget.build, etc.). This buries the useful dependency tree context generated by the Dart compiler under noise and makes user error look like a tool crash.
  2. Missing Actionable Remediation (Wasm Builds & Dry-Runs): When compilation aborts or dry-runs detect legacy web libraries (dart:html, package:js), zero explicit guidance is given on how to migrate to WebAssembly-compatible packages (dry-runs only print a generic docs URL).

Proposed Changes

  1. Modify Dart2WasmTarget.build to invoke ProcessUtils.run(throwOnError: false).
  2. On non-zero exit codes during non-dry-run builds, directly forward uncorrupted compiler stdout and stderr to environment.logger without throwing an unformatted ProcessException.
  3. Add a new shortlink helper constant in lib/src/web/web_constants.dart alongside kWasmMoreInfo targeting https://flutter.dev/to/wasm-errors (which will redirect to https://docs.flutter.dev/platform-integration/web/wasm#diagnosing-wasm-compilation-errors).
  4. In both fatal --wasm compilations and Wasm dry-run finding outputs (_handleDryRunResult), inspect output streams for instances of 'dart:html' or 'package:js'. When present, append an educational remediation footer:
    Note: WebAssembly compilation failed due to legacy web imports. 
    Migrate your project from dart:html and package:js to package:web and dart:js_interop.
    See https://flutter.dev/to/wasm-errors for diagnostic and migration guidance.
  5. For fatal --wasm builds, terminate execution cleanly via throwToolExit('Failed to compile application for the Web.'), preventing internal tool stack trace spillage.

Activity

  1. self-assigned this
    on Aug 3, 2026
  2. added
    toolAffects the "flutter" command-line tool. See also t: labels.
    platform-webWeb applications specifically
    a: buildBuilding flutter applications with the tool
    a: error messageError messages from the Flutter framework
    on Aug 3, 2026
  3. added a commit that references this issue on Aug 3, 2026
    5cdf198
  4. added a commit that references this issue on Aug 4, 2026
    84a72e6
  5. github-actions commented on Aug 18, 2026

    @github-actions

    This thread has been automatically locked since there has not been any recent activity after it was closed. If you are still experiencing a similar issue, please open a new bug, including the output of flutter doctor -v and a minimal reproduction of the issue.

  6. locked as resolved and limited conversation to collaborators on Aug 18, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

a: buildBuilding flutter applications with the toola: error messageError messages from the Flutter frameworkplatform-webWeb applications specificallytoolAffects the "flutter" command-line tool. See also t: labels.

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions