Sitelet https://github.com/flutter/flutter/pull/191990
Skip to content

[flutter_tools] Pause web server requests until initial compilation finishes - #191990

Merged
auto-submit[bot] merged 1 commit into
flutter:masterfrom
bkonyi:fix_web_server_startup_race
Aug 29, 2026
Merged

[flutter_tools] Pause web server requests until initial compilation finishes#191990
auto-submit[bot] merged 1 commit into
flutter:masterfrom
bkonyi:fix_web_server_startup_race

Conversation

@bkonyi

@bkonyi bkonyi commented Aug 28, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Description

When launching a web application using flutter run -d web-server, the HTTP server begins listening as soon as WebDevFS.create() starts WebAssetServer. However, application compilation in _updateDevFS() has not yet completed.

If a client requests the page before compilation finishes, DWDS attempts to read module metadata while _webMemoryFS.mergedMetadata is still null. DWDS then injects an empty module list into the bootstrap script (main_module.bootstrap.js) and permanently memoizes that 0 modules exist in MetadataProvider._metadataMemoizer, causing the page to only load dart_sdk.js and hang on a blank white screen. In Chrome console logs, this exhibits as DDC is about to load 1/2 scripts with pool size = 1000 with nothing else loading afterwards.

Additionally, if the client connects to DWDS before webDevFS.connect() starts listening, the connectedApps broadcast event is dropped without listeners, causing the tool to hang waiting for a connection.

This PR adds a readiness completer to WebAssetServer and a Shelf middleware to pause incoming HTTP requests until initial compilation completes and the DWDS connection listener is attached.

Related Issues

Fixes #191957

Tests

  • Added tests in packages/flutter_tools/test/general.shard/web/web_asset_server_test.dart verifying that isReady completes on markReady()/dispose() and that incoming HTTP requests are held until markReady() is called.
  • Added test in packages/flutter_tools/test/general.shard/resident_web_runner_test.dart verifying that ResidentWebRunner.run() marks WebDevFS as ready before starting the app.

@github-actions github-actions Bot added the tool Affects the "flutter" command-line tool. See also t: labels. label Aug 28, 2026
@bkonyi bkonyi added the CICD Run CI/CD label Aug 28, 2026
@bkonyi
bkonyi force-pushed the fix_web_server_startup_race branch from 56d6dae to 771cb39 Compare August 28, 2026 19:52
@bkonyi
bkonyi marked this pull request as ready for review August 28, 2026 20:34
@bkonyi
bkonyi requested review from Markzipan and nshahan August 28, 2026 20:34
gemini-code-assist[bot]
gemini-code-assist Bot reviewed Aug 28, 2026
View reviewed changes

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request introduces a mechanism to pause incoming requests to the web asset server until it is fully ready to handle them. It adds a markReady method to WebDevFS and WebAssetServer, and introduces a middleware that awaits this readiness before processing requests. The review feedback highlights a potential race condition in ResidentWebRunner where markReady is called synchronously after connect, potentially unpausing requests before the DWDS connection listener is registered, and suggests waiting for the connection to complete first.

Comment thread packages/flutter_tools/lib/src/isolated/resident_web_runner.dart
nshahan
nshahan reviewed Aug 28, 2026
View reviewed changes
Comment thread packages/flutter_tools/lib/src/isolated/resident_web_runner.dart
final Future<ConnectionResult?>? connectDebug = supportsServiceProtocol
? webDevFS.connect(useDebugExtension)
: null;
webDevFS.markReady();

@nshahan nshahan Aug 28, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I can't reason through why this is the right place to call markReady(). What is the signal we're waiting for that tells us the necessary work is done and it is now safe to respond to web requests?

@bkonyi bkonyi Aug 28, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is the point where we know compilation is complete and that we're ready to listen for connected applications. I've added a comment here to document why this is the right place to mark the server as ready to accept connections.

@bkonyi
bkonyi force-pushed the fix_web_server_startup_race branch from 771cb39 to b15326d Compare August 28, 2026 23:30
@bkonyi
[flutter_tools] Pause web server requests until initial compilation f…
1ae47a1 
…inishes

When launching an application using `flutter run -d web-server`, the HTTP server begins listening as soon as `WebDevFS.create()` starts `WebAssetServer`. However, the application compilation in `_updateDevFS()` has not yet completed.

If a client requests the page before compilation finishes, DWDS attempts to read module metadata while `_webMemoryFS.mergedMetadata` is still null. DWDS then injects an empty module list into the bootstrap script and permanently memoizes that 0 modules exist, causing the page to only load `dart_sdk.js` and hang on a blank white screen. Additionally, if the client connects to DWDS before `webDevFS.connect()` starts listening, the `connectedApps` broadcast event is dropped.

This adds a readiness completer to `WebAssetServer` and a Shelf middleware to pause incoming requests until initial compilation completes and the DWDS connection listener is attached.

Fixes flutter#191957
@bkonyi
bkonyi force-pushed the fix_web_server_startup_race branch from b15326d to 1ae47a1 Compare August 28, 2026 23:37
nshahan
nshahan approved these changes Aug 28, 2026
View reviewed changes

@nshahan nshahan left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks!

@bkonyi bkonyi added the autosubmit Merge PR when tree becomes green via auto submit App label Aug 28, 2026
@auto-submit

auto-submit Bot commented Aug 29, 2026

Copy link
Copy Markdown
Contributor

autosubmit label was removed for flutter/flutter/191990, because - The status or check suite Dashboard Checks has failed. Please fix the issues identified (or deflake) before re-applying this label.

@auto-submit auto-submit Bot removed the autosubmit Merge PR when tree becomes green via auto submit App label Aug 29, 2026
@bkonyi bkonyi added the autosubmit Merge PR when tree becomes green via auto submit App label Aug 29, 2026
@auto-submit
auto-submit Bot added this pull request to the merge queue Aug 29, 2026
Merged via the queue into flutter:master with commit 625c5c9 Aug 29, 2026
29 checks passed
@flutter-dashboard flutter-dashboard Bot removed the autosubmit Merge PR when tree becomes green via auto submit App label Aug 29, 2026
This was referenced Aug 29, 2026
Closed
Closed
Closed
Closed
Merged
auto-submit Bot pushed a commit to flutter/packages that referenced this pull request Aug 30, 2026
@engine-flutter-autoroll
Roll Flutter from 8d8c1aabb47a to c97838627ff5 (20 revisions) (#12693)
d642322 
flutter/flutter@8d8c1aa...c978386

2026-08-30 engine-flutter-autoroll@skia.org Roll Skia from ce359c7fbfe6 to 588b550a4dd8 (1 revision) (flutter/flutter#192040)
2026-08-30 engine-flutter-autoroll@skia.org Roll Skia from 3ae8e3d1e335 to ce359c7fbfe6 (1 revision) (flutter/flutter#192037)
2026-08-30 engine-flutter-autoroll@skia.org Roll Fuchsia Linux SDK from J123CwfDPYyVDpkMl... to o9DikEfRoFyVK3LKD... (flutter/flutter#192031)
2026-08-29 44747303+theprantadutta@users.noreply.github.com Make the AbsorbPointer sample show the difference from IgnorePointer (flutter/flutter#188940)
2026-08-29 engine-flutter-autoroll@skia.org Roll Dart SDK from 391ff83cd1d3 to 76abdf94faa8 (1 revision) (flutter/flutter#192021)
2026-08-29 engine-flutter-autoroll@skia.org Roll Skia from b392fb672d13 to 3ae8e3d1e335 (1 revision) (flutter/flutter#192020)
2026-08-29 engine-flutter-autoroll@skia.org Roll Skia from 0b4249b26b38 to b392fb672d13 (6 revisions) (flutter/flutter#192016)
2026-08-29 97480502+b-luk@users.noreply.github.com Fixes for texture-backed gradients (flutter/flutter#191925)
2026-08-29 engine-flutter-autoroll@skia.org Roll Dart SDK from ae63a6eca3f1 to 391ff83cd1d3 (3 revisions) (flutter/flutter#192010)
2026-08-29 166619967+ik020@users.noreply.github.com Fix Android license detection for cmdline-tools 23.0+ (flutter/flutter#191554)
2026-08-29 bkonyi@google.com [flutter_tools] Pause web server requests until initial compilation finishes (flutter/flutter#191990)
2026-08-28 codefu@google.com fix(workflow): Mac Verify Binaries needs `Linux mac_android_aot_engine` (flutter/flutter#191999)
2026-08-28 engine-flutter-autoroll@skia.org Roll Fuchsia Linux SDK from dDxH8G5cDBP602eyG... to J123CwfDPYyVDpkMl... (flutter/flutter#191984)
2026-08-28 katelovett@google.com Update scheduled workflow for more tasks, add goldctl update (flutter/flutter#191991)
2026-08-28 katelovett@google.com Update no-main-prs to leave a comment (flutter/flutter#191973)
2026-08-28 269567208+reidbaker-agent@users.noreply.github.com [AGP 9.1.0 Migration #4] Replace plugin build-type copy with initWith on public DSL (flutter/flutter#191606)
2026-08-28 engine-flutter-autoroll@skia.org Roll Skia from fe0b9a5261f9 to 0b4249b26b38 (1 revision) (flutter/flutter#191974)
2026-08-28 louisehsu@google.com [UIScene] Migrate dev/benchmarks/macrobenchmarks to UIScene lifecycle (flutter/flutter#191648)
2026-08-28 louisehsu@google.com Uiscene migrate remaining apps (flutter/flutter#191652)
2026-08-28 bkonyi@google.com [tool] Migrate SymbolizeCommand to modular dependency injection (flutter/flutter#190744)

If this roll has caused a breakage, revert this CL and stop the roller
using the controls here:
https://autoroll.skia.org/r/flutter-packages
Please CC bmparr@google.com,stuartmorgan@google.com on the revert to ensure that a human
is aware of the problem.

To file a bug in Packages: https://github.com/flutter/flutter/issues/new/choose

To report a problem with the AutoRoller itself, please file a bug:
https://issues.skia.org/issues/new?component=1389291&template=1850622

Documentation for the AutoRoller is here:
https://skia.googlesource.com/buildbot/+doc/main/autoroll/README.md
@justinmc justinmc mentioned this pull request Sep 4, 2026
Open
victorsanni pushed a commit to victorsanni/packages that referenced this pull request Sep 9, 2026
@engine-flutter-autoroll @victorsanni
Roll Flutter from 8d8c1aabb47a to c97838627ff5 (20 revisions) (flutte…
4eba533 
…r#12693)

flutter/flutter@8d8c1aa...c978386

2026-08-30 engine-flutter-autoroll@skia.org Roll Skia from ce359c7fbfe6 to 588b550a4dd8 (1 revision) (flutter/flutter#192040)
2026-08-30 engine-flutter-autoroll@skia.org Roll Skia from 3ae8e3d1e335 to ce359c7fbfe6 (1 revision) (flutter/flutter#192037)
2026-08-30 engine-flutter-autoroll@skia.org Roll Fuchsia Linux SDK from J123CwfDPYyVDpkMl... to o9DikEfRoFyVK3LKD... (flutter/flutter#192031)
2026-08-29 44747303+theprantadutta@users.noreply.github.com Make the AbsorbPointer sample show the difference from IgnorePointer (flutter/flutter#188940)
2026-08-29 engine-flutter-autoroll@skia.org Roll Dart SDK from 391ff83cd1d3 to 76abdf94faa8 (1 revision) (flutter/flutter#192021)
2026-08-29 engine-flutter-autoroll@skia.org Roll Skia from b392fb672d13 to 3ae8e3d1e335 (1 revision) (flutter/flutter#192020)
2026-08-29 engine-flutter-autoroll@skia.org Roll Skia from 0b4249b26b38 to b392fb672d13 (6 revisions) (flutter/flutter#192016)
2026-08-29 97480502+b-luk@users.noreply.github.com Fixes for texture-backed gradients (flutter/flutter#191925)
2026-08-29 engine-flutter-autoroll@skia.org Roll Dart SDK from ae63a6eca3f1 to 391ff83cd1d3 (3 revisions) (flutter/flutter#192010)
2026-08-29 166619967+ik020@users.noreply.github.com Fix Android license detection for cmdline-tools 23.0+ (flutter/flutter#191554)
2026-08-29 bkonyi@google.com [flutter_tools] Pause web server requests until initial compilation finishes (flutter/flutter#191990)
2026-08-28 codefu@google.com fix(workflow): Mac Verify Binaries needs `Linux mac_android_aot_engine` (flutter/flutter#191999)
2026-08-28 engine-flutter-autoroll@skia.org Roll Fuchsia Linux SDK from dDxH8G5cDBP602eyG... to J123CwfDPYyVDpkMl... (flutter/flutter#191984)
2026-08-28 katelovett@google.com Update scheduled workflow for more tasks, add goldctl update (flutter/flutter#191991)
2026-08-28 katelovett@google.com Update no-main-prs to leave a comment (flutter/flutter#191973)
2026-08-28 269567208+reidbaker-agent@users.noreply.github.com [AGP 9.1.0 Migration flutter#4] Replace plugin build-type copy with initWith on public DSL (flutter/flutter#191606)
2026-08-28 engine-flutter-autoroll@skia.org Roll Skia from fe0b9a5261f9 to 0b4249b26b38 (1 revision) (flutter/flutter#191974)
2026-08-28 louisehsu@google.com [UIScene] Migrate dev/benchmarks/macrobenchmarks to UIScene lifecycle (flutter/flutter#191648)
2026-08-28 louisehsu@google.com Uiscene migrate remaining apps (flutter/flutter#191652)
2026-08-28 bkonyi@google.com [tool] Migrate SymbolizeCommand to modular dependency injection (flutter/flutter#190744)

If this roll has caused a breakage, revert this CL and stop the roller
using the controls here:
https://autoroll.skia.org/r/flutter-packages
Please CC bmparr@google.com,stuartmorgan@google.com on the revert to ensure that a human
is aware of the problem.

To file a bug in Packages: https://github.com/flutter/flutter/issues/new/choose

To report a problem with the AutoRoller itself, please file a bug:
https://issues.skia.org/issues/new?component=1389291&template=1850622

Documentation for the AutoRoller is here:
https://skia.googlesource.com/buildbot/+doc/main/autoroll/README.md
victorsanni pushed a commit to victorsanni/packages that referenced this pull request Sep 9, 2026
@engine-flutter-autoroll @victorsanni
Roll Flutter from 8d8c1aabb47a to c97838627ff5 (20 revisions) (flutte…
637f409 
…r#12693)

flutter/flutter@8d8c1aa...c978386

2026-08-30 engine-flutter-autoroll@skia.org Roll Skia from ce359c7fbfe6 to 588b550a4dd8 (1 revision) (flutter/flutter#192040)
2026-08-30 engine-flutter-autoroll@skia.org Roll Skia from 3ae8e3d1e335 to ce359c7fbfe6 (1 revision) (flutter/flutter#192037)
2026-08-30 engine-flutter-autoroll@skia.org Roll Fuchsia Linux SDK from J123CwfDPYyVDpkMl... to o9DikEfRoFyVK3LKD... (flutter/flutter#192031)
2026-08-29 44747303+theprantadutta@users.noreply.github.com Make the AbsorbPointer sample show the difference from IgnorePointer (flutter/flutter#188940)
2026-08-29 engine-flutter-autoroll@skia.org Roll Dart SDK from 391ff83cd1d3 to 76abdf94faa8 (1 revision) (flutter/flutter#192021)
2026-08-29 engine-flutter-autoroll@skia.org Roll Skia from b392fb672d13 to 3ae8e3d1e335 (1 revision) (flutter/flutter#192020)
2026-08-29 engine-flutter-autoroll@skia.org Roll Skia from 0b4249b26b38 to b392fb672d13 (6 revisions) (flutter/flutter#192016)
2026-08-29 97480502+b-luk@users.noreply.github.com Fixes for texture-backed gradients (flutter/flutter#191925)
2026-08-29 engine-flutter-autoroll@skia.org Roll Dart SDK from ae63a6eca3f1 to 391ff83cd1d3 (3 revisions) (flutter/flutter#192010)
2026-08-29 166619967+ik020@users.noreply.github.com Fix Android license detection for cmdline-tools 23.0+ (flutter/flutter#191554)
2026-08-29 bkonyi@google.com [flutter_tools] Pause web server requests until initial compilation finishes (flutter/flutter#191990)
2026-08-28 codefu@google.com fix(workflow): Mac Verify Binaries needs `Linux mac_android_aot_engine` (flutter/flutter#191999)
2026-08-28 engine-flutter-autoroll@skia.org Roll Fuchsia Linux SDK from dDxH8G5cDBP602eyG... to J123CwfDPYyVDpkMl... (flutter/flutter#191984)
2026-08-28 katelovett@google.com Update scheduled workflow for more tasks, add goldctl update (flutter/flutter#191991)
2026-08-28 katelovett@google.com Update no-main-prs to leave a comment (flutter/flutter#191973)
2026-08-28 269567208+reidbaker-agent@users.noreply.github.com [AGP 9.1.0 Migration flutter#4] Replace plugin build-type copy with initWith on public DSL (flutter/flutter#191606)
2026-08-28 engine-flutter-autoroll@skia.org Roll Skia from fe0b9a5261f9 to 0b4249b26b38 (1 revision) (flutter/flutter#191974)
2026-08-28 louisehsu@google.com [UIScene] Migrate dev/benchmarks/macrobenchmarks to UIScene lifecycle (flutter/flutter#191648)
2026-08-28 louisehsu@google.com Uiscene migrate remaining apps (flutter/flutter#191652)
2026-08-28 bkonyi@google.com [tool] Migrate SymbolizeCommand to modular dependency injection (flutter/flutter#190744)

If this roll has caused a breakage, revert this CL and stop the roller
using the controls here:
https://autoroll.skia.org/r/flutter-packages
Please CC bmparr@google.com,stuartmorgan@google.com on the revert to ensure that a human
is aware of the problem.

To file a bug in Packages: https://github.com/flutter/flutter/issues/new/choose

To report a problem with the AutoRoller itself, please file a bug:
https://issues.skia.org/issues/new?component=1389291&template=1850622

Documentation for the AutoRoller is here:
https://skia.googlesource.com/buildbot/+doc/main/autoroll/README.md
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@nshahan nshahan nshahan approved these changes
@Markzipan Markzipan Awaiting requested review from Markzipan
+1 more reviewer
@gemini-code-assist gemini-code-assist[bot] gemini-code-assist[bot] left review comments
Reviewers whose approvals may not affect merge requirements

Assignees

No one assigned

Labels

CICD Run CI/CD tool Affects the "flutter" command-line tool. See also t: labels.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Browser stuck on white screen when accessing dev server before compilation finishes

2 participants

@bkonyi @nshahan