fix(overlay): keep a runtime error raised during the initial load by alexander-akait · Pull Request #5745 · webpack/webpack-dev-server

alexander-akait · 2026-09-19T15:18:11Z

Summary

Closes #5024. An error thrown while the entry is still evaluating raises the overlay before the client's socket handshake completes; the compilation itself succeeded, so the handshake's ok arrived milliseconds later and sent DISMISS, closing an overlay it knew nothing about (measured: error at +50ms, overlay at +67ms, ok at +73ms, overlay gone at +74ms — and reloadApp then returns early on its isInitial guard, so nothing puts it back).

ok and still-ok now send a new BUILD_OK event that only the build-error state handles. invalid keeps sending DISMISS, because a rebuild replaces the code a runtime error came from — so editing the file still clears a runtime overlay exactly as it does today, rather than leaving a stale one after an HMR update that does not reload the page.

What kind of change does this PR introduce?

fix

Did you add tests for your changes?

Yes. test/e2e/overlay.test.js gains "should keep the overlay for a runtime error thrown during the initial load", driven by a new fixture (test/fixtures/overlay-config/throw-on-initial-load.js) that throws during entry evaluation — the existing runtime-error tests inject via addScriptTag after networkidle0, which is the already-working path and is why nothing caught this. Verified against a client built from unmodified client-src: it fails with expect(received).not.toBeNull() / Received: null, and passes after rebuilding with the fix. test/client/overlay-lifecycle.test.js adds a state-machine case pinning that BUILD_OK clears a build error but not a runtime one, and test/client/index.test.js is updated where it pinned the old still-ok behaviour.

Does this PR introduce a breaking change?

No.

If relevant, what needs to be documented once your changes are merged or what have you already documented?

n/a — the overlay's documented behaviour is unchanged; this only stops it closing an error it was meant to show.

Use of AI

AI-assisted (Claude Code). It was used to reproduce the issue in a browser — instrumenting WebSocket and a MutationObserver to get the causal ordering above — and to draft the fix and the tests. Every claim here was verified by running it: the regression test was confirmed to fail on an unmodified client and pass with the fix, the full overlay suite (39/39) and test/client/** pass, and npm run lint exits 0. All output was reviewed before committing.

🤖 Generated with Claude Code

https://claude.ai/code/session_01UjuMAuk9o6UazjHzcAQCTA

Generated by Claude Code

Summary by CodeRabbit

Bug Fixes
- Runtime-error overlays now remain visible when errors occur during initial page load.
- Successful builds dismiss build-error overlays without hiding runtime-error overlays.
- Runtime-error overlays can still be dismissed explicitly.
- Overlay behavior now correctly distinguishes build status from runtime errors.
Tests
- Added coverage for overlay behavior during initial loading, successful builds, and explicit dismissal.

An error thrown while the entry is still evaluating raises the overlay before the client's socket handshake completes. The compilation itself succeeded, so the handshake's `ok` arrived milliseconds later and sent `DISMISS`, closing an overlay it knew nothing about. `ok` and `still-ok` now send `BUILD_OK`, which only the build-error state handles. `invalid` keeps sending `DISMISS`: a rebuild replaces the code a runtime error came from, so that overlay is stale too. Closes #5024

changeset-bot · 2026-09-19T15:18:15Z

🦋 Changeset detected

Latest commit: f40996e

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
webpack-dev-server	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

coderabbitai · 2026-09-19T15:21:06Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: c8a1b21e-1e54-49ab-805e-097421fd7f1c

📥 Commits

Reviewing files that changed from the base of the PR and between 25562a3 and f40996e.

📒 Files selected for processing (1)

test/client/index.test.js

Included review availability: Your plan provides up to 8 included reviews per hour; 7 remain after this review.

Walkthrough

The client now sends BUILD_OK for successful and unchanged compilations. The overlay handles BUILD_OK by hiding build errors while preserving runtime errors. Unit tests cover both overlay states. An end-to-end test verifies that a runtime error thrown during initial page loading remains visible. A patch changeset documents the fix.

Priority: ➖ Normal

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the primary change: preserving a runtime error overlay during the initial page load.
Linked Issues check	✅ Passed	Issue `#5024` requires the initial-load runtime-error overlay to remain visible. `ok` and `still-ok` now send `BUILD_OK`, and the overlay handles `BUILD_OK` only in the build-error state. Therefore, a r…
Out of Scope Changes check	✅ Passed	The changes stay within issue `#5024`. They update client and overlay message handling, add focused unit and lifecycle tests, add the initial-load runtime-error fixture and e2e regression test, and add …
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 6…

✨ Finishing Touches

📝 Generate docstrings

Commit to this branch
Create a new PR

🧪 Generate unit tests (beta)

Commit to this branch
Create a new PR

Warning

Some tools did not complete. Review the errors below.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

test/client/index.test.js

ESLint failed to execute (timeout).

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

codecov · 2026-09-19T17:01:29Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 90.83%. Comparing base (d09c426) to head (f40996e).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #5745      +/-   ##
==========================================
+ Coverage   90.29%   90.83%   +0.54%     
==========================================
  Files          13       13              
  Lines        6241     6282      +41     
==========================================
+ Hits         5635     5706      +71     
+ Misses        606      576      -30

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

test(overlay): cover invalid/ok overlay dismissal in the client

f40996e

alexander-akait merged commit e44bdae into main Sep 20, 2026
17 checks passed

alexander-akait deleted the fix/overlay-dismissed-on-initial-load branch September 20, 2026 11:25

github-actions Bot mentioned this pull request Sep 20, 2026

chore(release): new release #5740

Open

Navigation Menu

Uh oh!

fix(overlay): keep a runtime error raised during the initial load - #5745

fix(overlay): keep a runtime error raised during the initial load#5745
alexander-akait merged 2 commits into
mainfrom
fix/overlay-dismissed-on-initial-load

alexander-akait commented Sep 19, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

changeset-bot Bot commented Sep 19, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Sep 19, 2026 •

edited

Loading

Uh oh!

codecov Bot commented Sep 19, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

alexander-akait commented Sep 19, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by CodeRabbit

Uh oh!

changeset-bot Bot commented Sep 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

coderabbitai Bot commented Sep 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Uh oh!

codecov Bot commented Sep 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

alexander-akait commented Sep 19, 2026 •

edited by coderabbitai Bot

Loading

changeset-bot Bot commented Sep 19, 2026 •

edited

Loading

coderabbitai Bot commented Sep 19, 2026 •

edited

Loading

codecov Bot commented Sep 19, 2026 •

edited

Loading