feat: enhance error handling for script loading and execution by 2heal1 · Pull Request #4538 · module-federation/core

2heal1 · 2026-03-13T08:16:02Z

Description

feat: improve script load error discrimination and retry guard

Background

Previously, all failures in loadEntryScript — network 404, CORS, timeout, and IIFE runtime exceptions — were reported uniformly as
RUNTIME-008 with no distinguishing detail. Additionally, when a script's IIFE threw during execution, script.onload still fired (standard
browser behavior), silently discarding the original exception.

Changes

packages/sdk/src/dom.ts

Register window.addEventListener('error', executionErrorHandler) before the script is appended, capturing IIFE runtime exceptions by
matching evt.filename against the script URL
script.onerror now creates a ScriptNetworkError (with err.name set) to explicitly identify network-level failures
Both error types call onErrorCallback instead of cb; onload no longer invokes cb when an execution error was captured
window.removeEventListener is called unconditionally after onload / onerror

packages/runtime-core/src/utils/load.ts

loadEntryScript switched to the two-argument .then(onFulfilled, onRejected) form, so RUNTIME-001 errors thrown inside
handleRemoteEntryLoaded are not mistakenly caught and re-reported as RUNTIME-008
onRejected forwards the original error message from loadScript rejection into the RUNTIME-008 error
isScriptLoadError now excludes ScriptExecutionError: retrying a script that failed at execution time is pointless, so loadEntryError is
not emitted and the retry-plugin is never triggered

Tests

packages/sdk/tests/dom.spec.ts: 5 new cases covering ScriptNetworkError, ScriptExecutionError, no false trigger from a different URL,
and listener cleanup
packages/runtime-core/tests/load.spec.ts: integration tests using real fixture files covering 4 scenarios — missing script, execution
error, global not registered, and successful load

Docs

docs/zh/guide/troubleshooting/runtime.mdx and docs/en/guide/troubleshooting/runtime.mdx: RUNTIME-008 section expanded with two error
subtypes (ScriptNetworkError / ScriptExecutionError), their causes, and targeted troubleshooting steps

changeset-bot · 2026-03-13T08:16:07Z

🦋 Changeset detected

Latest commit: 6c76d23

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

This PR includes changesets to release 45 packages

Name	Type
@module-federation/runtime-core	Patch
@module-federation/sdk	Patch
@module-federation/runtime	Patch
@module-federation/bridge-react	Patch
@module-federation/devtools	Patch
@module-federation/cli	Patch
@module-federation/data-prefetch	Patch
@module-federation/dts-plugin	Patch
@module-federation/enhanced	Patch
@module-federation/esbuild	Patch
@module-federation/managers	Patch
@module-federation/manifest	Patch
@module-federation/metro	Patch
@module-federation/modern-js-v3	Patch
@module-federation/modern-js	Patch
@module-federation/nextjs-mf	Patch
@module-federation/node	Patch
@module-federation/retry-plugin	Patch
@module-federation/rsbuild-plugin	Patch
@module-federation/rspack	Patch
@module-federation/rspress-plugin	Patch
@module-federation/storybook-addon	Patch
@module-federation/utilities	Patch
@module-federation/webpack-bundler-runtime	Patch
@module-federation/bridge-react-webpack-plugin	Patch
@module-federation/bridge-vue3	Patch
@module-federation/runtime-tools	Patch
shared-tree-shaking-no-server-host	Patch
shared-tree-shaking-no-server-provider	Patch
@module-federation/metro-plugin-rnc-cli	Patch
@module-federation/metro-plugin-rnef	Patch
shared-tree-shaking-with-server-host	Patch
shared-tree-shaking-with-server-provider	Patch
node-dynamic-remote-new-version	Patch
node-dynamic-remote	Patch
remote5	Patch
remote6	Patch
website-new	Patch
@module-federation/inject-external-runtime-core-plugin	Patch
@module-federation/third-party-dts-extractor	Patch
@module-federation/bridge-shared	Patch
@module-federation/error-codes	Patch
create-module-federation	Patch
@module-federation/treeshake-server	Patch
@module-federation/treeshake-frontend	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

netlify · 2026-03-13T08:16:09Z

✅ Deploy Preview for module-federation-docs ready!

Name	Link
🔨 Latest commit	`6c76d23`
🔍 Latest deploy log	https://app.netlify.com/projects/module-federation-docs/deploys/69b3e688b557c30008b3afa1
😎 Deploy Preview	https://deploy-preview-4538--module-federation-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

pkg-pr-new · 2026-03-13T08:19:52Z

Open in StackBlitz

@module-federation/devtools

pnpm add https://pkg.pr.new/@module-federation/devtools@35ec6a9

@module-federation/cli

pnpm add https://pkg.pr.new/@module-federation/cli@35ec6a9

create-module-federation

pnpm add https://pkg.pr.new/create-module-federation@35ec6a9

@module-federation/data-prefetch

pnpm add https://pkg.pr.new/@module-federation/data-prefetch@35ec6a9

@module-federation/dts-plugin

pnpm add https://pkg.pr.new/@module-federation/dts-plugin@35ec6a9

@module-federation/enhanced

pnpm add https://pkg.pr.new/@module-federation/enhanced@35ec6a9

@module-federation/error-codes

pnpm add https://pkg.pr.new/@module-federation/error-codes@35ec6a9

@module-federation/esbuild

pnpm add https://pkg.pr.new/@module-federation/esbuild@35ec6a9

@module-federation/managers

pnpm add https://pkg.pr.new/@module-federation/managers@35ec6a9

@module-federation/manifest

pnpm add https://pkg.pr.new/@module-federation/manifest@35ec6a9

@module-federation/metro

pnpm add https://pkg.pr.new/@module-federation/metro@35ec6a9

@module-federation/metro-plugin-rnc-cli

pnpm add https://pkg.pr.new/@module-federation/metro-plugin-rnc-cli@35ec6a9

@module-federation/metro-plugin-rnef

pnpm add https://pkg.pr.new/@module-federation/metro-plugin-rnef@35ec6a9

@module-federation/modern-js

pnpm add https://pkg.pr.new/@module-federation/modern-js@35ec6a9

@module-federation/modern-js-v3

pnpm add https://pkg.pr.new/@module-federation/modern-js-v3@35ec6a9

@module-federation/native-federation-tests

pnpm add https://pkg.pr.new/@module-federation/native-federation-tests@35ec6a9

@module-federation/native-federation-typescript

pnpm add https://pkg.pr.new/@module-federation/native-federation-typescript@35ec6a9

@module-federation/nextjs-mf

pnpm add https://pkg.pr.new/@module-federation/nextjs-mf@35ec6a9

@module-federation/node

pnpm add https://pkg.pr.new/@module-federation/node@35ec6a9

@module-federation/retry-plugin

pnpm add https://pkg.pr.new/@module-federation/retry-plugin@35ec6a9

@module-federation/rsbuild-plugin

pnpm add https://pkg.pr.new/@module-federation/rsbuild-plugin@35ec6a9

@module-federation/rspack

pnpm add https://pkg.pr.new/@module-federation/rspack@35ec6a9

@module-federation/rspress-plugin

pnpm add https://pkg.pr.new/@module-federation/rspress-plugin@35ec6a9

@module-federation/runtime

pnpm add https://pkg.pr.new/@module-federation/runtime@35ec6a9

@module-federation/runtime-core

pnpm add https://pkg.pr.new/@module-federation/runtime-core@35ec6a9

@module-federation/runtime-tools

pnpm add https://pkg.pr.new/@module-federation/runtime-tools@35ec6a9

@module-federation/sdk

pnpm add https://pkg.pr.new/@module-federation/sdk@35ec6a9

@module-federation/storybook-addon

pnpm add https://pkg.pr.new/@module-federation/storybook-addon@35ec6a9

@module-federation/third-party-dts-extractor

pnpm add https://pkg.pr.new/@module-federation/third-party-dts-extractor@35ec6a9

@module-federation/treeshake-frontend

pnpm add https://pkg.pr.new/@module-federation/treeshake-frontend@35ec6a9

@module-federation/treeshake-server

pnpm add https://pkg.pr.new/@module-federation/treeshake-server@35ec6a9

@module-federation/typescript

pnpm add https://pkg.pr.new/@module-federation/typescript@35ec6a9

@module-federation/utilities

pnpm add https://pkg.pr.new/@module-federation/utilities@35ec6a9

@module-federation/webpack-bundler-runtime

pnpm add https://pkg.pr.new/@module-federation/webpack-bundler-runtime@35ec6a9

@module-federation/bridge-react

pnpm add https://pkg.pr.new/@module-federation/bridge-react@35ec6a9

@module-federation/bridge-react-webpack-plugin

pnpm add https://pkg.pr.new/@module-federation/bridge-react-webpack-plugin@35ec6a9

@module-federation/bridge-shared

pnpm add https://pkg.pr.new/@module-federation/bridge-shared@35ec6a9

@module-federation/bridge-vue3

pnpm add https://pkg.pr.new/@module-federation/bridge-vue3@35ec6a9

@module-federation/inject-external-runtime-core-plugin

pnpm add https://pkg.pr.new/@module-federation/inject-external-runtime-core-plugin@35ec6a9

commit: 35ec6a9

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9258f5815c

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

chatgpt-codex-connector · 2026-03-13T08:20:22Z

packages/runtime-core/src/utils/load.ts

+  }).then(
+    () => {
+      // loadScript resolved: script was fetched, executed without throwing, and
+      // did not trigger a ScriptExecutionError listener. Now verify the global was registered.
      return handleRemoteEntryLoaded(name, globalName, entry);


Preserve RUNTIME_008 mapping for script timeouts

Switching to .then(onFulfilled, onRejected) means any error thrown in handleRemoteEntryLoaded now bypasses the RUNTIME_008 wrapper, but loadScript timeouts still resolve (the timeout path in packages/sdk/src/dom.ts calls the success callback), so a timed-out remote now falls into this fulfillment branch and is rethrown as RUNTIME_001 instead of RUNTIME_008. In timeout conditions this breaks retry-plugin triggering (loadEntryError only runs on RUNTIME_008) and changes user-facing diagnostics from load failure to missing global.

Useful? React with 👍 / 👎.

github-actions · 2026-03-13T08:26:26Z

Bundle Size Report

15 package(s) changed, 25 unchanged.

Package dist + ESM entry

Package	Total dist (raw)	Delta	ESM gzip	Delta
`@module-federation/bridge-react`	361.3 kB	+2.8 kB (+0.8%)	1.3 kB	no change
`@module-federation/bridge-vue3`	144.0 kB	+1.7 kB (+1.2%)	22.1 kB	+275 B (+1.2%)
`@module-federation/cli`	26.7 kB	no change	786 B	no change
`@module-federation/core`	39.1 kB	no change	173 B	no change
`@module-federation/devtools`	473.2 kB	no change	3.9 kB	no change
`@module-federation/enhanced`	809.4 kB	-1411 B (-0.2%)	672 B	-40 B (-5.6%)
`@module-federation/inject-external-runtime-core-plugin`	5.4 kB	-26 B (-0.5%)	548 B	no change
`@module-federation/managers`	69.9 kB	no change	334 B	no change
`@module-federation/manifest`	138.4 kB	no change	182 B	no change
`@module-federation/metro-plugin-rnc-cli`	0 B	no change	314 B	no change
`@module-federation/node`	189.2 kB	no change	217 B	no change
`@module-federation/runtime-core`	251.8 kB	+514 B (+0.2%)	477 B	no change
`@module-federation/sdk`	120.5 kB	+1.9 kB (+1.6%)	798 B	no change
`@module-federation/storybook-addon`	76.5 kB	no change	100 B	no change
`@module-federation/utilities`	110.6 kB	no change	328 B	no change

Bundle targets

Package	Web bundle (gzip)	Delta	Node bundle (gzip)	Delta
`@module-federation/bridge-react`	17.4 kB	+250 B (+1.4%)	17.8 kB	+240 B (+1.3%)
`@module-federation/bridge-vue3`	16.9 kB	+254 B (+1.5%)	16.6 kB	+249 B (+1.5%)
`@module-federation/cli`	2.3 kB	-34 B (-1.4%)	2.3 kB	-34 B (-1.4%)
`@module-federation/core`	1.1 kB	-33 B (-2.9%)	1.0 kB	-32 B (-3.0%)
`@module-federation/devtools`	20.8 kB	-32 B (-0.1%)	20.8 kB	-32 B (-0.1%)
`@module-federation/enhanced`	3.0 kB	-3048 B (-49.7%)	3.0 kB	-3048 B (-49.7%)
`@module-federation/inject-external-runtime-core-plugin`	405 B	no change	405 B	no change
`@module-federation/managers`	2.4 kB	-28 B (-1.1%)	2.4 kB	-28 B (-1.1%)
`@module-federation/manifest`	6.2 kB	-40 B (-0.6%)	6.2 kB	-40 B (-0.6%)
`@module-federation/metro-plugin-rnc-cli`	411 B	-26 B (-5.9%)	411 B	-26 B (-5.9%)
`@module-federation/node`	9.2 kB	-29 B (-0.3%)	9.2 kB	-29 B (-0.3%)
`@module-federation/runtime-core`	13.7 kB	+30 B (+0.2%)	13.4 kB	+21 B (+0.2%)
`@module-federation/sdk`	4.6 kB	+241 B (+5.3%)	5.5 kB	+237 B (+4.4%)
`@module-federation/storybook-addon`	1.9 kB	-24 B (-1.2%)	1.7 kB	-24 B (-1.3%)
`@module-federation/utilities`	2.6 kB	-33 B (-1.2%)	2.6 kB	-33 B (-1.2%)

Consumer scenarios

Scenario	Web output (gzip)	Delta	Node output (gzip)	Delta	Gap (node-web)	Delta
Enhanced remoteEntry	19.5 kB	+227 B (+1.2%)	20.5 kB	+220 B (+1.1%)	+1.0 kB	-7 B

Total dist (raw): 6.30 MB (+5.5 kB (+0.1%))
Total ESM gzip: 73.4 kB (+235 B (+0.3%))
Total web bundle (gzip): 178.0 kB (-2552 B (-1.4%))
Total node bundle (gzip): 178.5 kB (-2579 B (-1.4%))
Tracked ./bundler entry gzip: 556 B (no change)
Tracked ./bundler web bundle (gzip): 4.5 kB (no change)
Tracked ./bundler node bundle (gzip): 4.5 kB (no change)

Bundle sizes are generated with rslib (Rspack). Package-root metrics preserve the historical report. Tracked subpath exports such as ./bundler are measured separately so ENV_TARGET-driven tree-shaking is visible. Bare imports are externalized to keep package-level sizes consistent, and assets are emitted as resources.

github-actions bot added the change: feat label Mar 13, 2026

feat: enhance error handling for script loading and execution

94d6139

2heal1 force-pushed the feat/error-capture branch from 9258f58 to 94d6139 Compare March 13, 2026 08:19

2heal1 temporarily deployed to npm March 13, 2026 08:20 — with GitHub Actions Inactive

chatgpt-codex-connector bot reviewed Mar 13, 2026

View reviewed changes

Merge branch 'main' into feat/error-capture

45ecc44

2heal1 temporarily deployed to npm March 13, 2026 09:17 — with GitHub Actions Inactive

danpeen approved these changes Mar 13, 2026

View reviewed changes

2heal1 added 2 commits March 13, 2026 18:03

refactor: use lazyRequire for dynamic imports in dependencies

075a055

chore: fix ts version

6c76d23

2heal1 merged commit e5dd6ef into main Mar 13, 2026
25 checks passed

2heal1 deleted the feat/error-capture branch March 13, 2026 10:45

2heal1 mentioned this pull request Mar 14, 2026

Release v2.2.0 #4541

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: enhance error handling for script loading and execution#4538

feat: enhance error handling for script loading and execution#4538
2heal1 merged 4 commits intomainfrom
feat/error-capture

2heal1 commented Mar 13, 2026

Uh oh!

changeset-bot bot commented Mar 13, 2026 •

edited

Loading

Uh oh!

netlify bot commented Mar 13, 2026 •

edited

Loading

Uh oh!

pkg-pr-new bot commented Mar 13, 2026 •

edited

Loading

Uh oh!

chatgpt-codex-connector bot left a comment

Uh oh!

chatgpt-codex-connector bot Mar 13, 2026

Uh oh!

github-actions bot commented Mar 13, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

2heal1 commented Mar 13, 2026

Description

Background

Changes

Tests

Docs

Uh oh!

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

Uh oh!

🦋 Changeset detected

Uh oh!

netlify bot commented Mar 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for module-federation-docs ready!

Uh oh!

pkg-pr-new bot commented Mar 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector bot Mar 13, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Mar 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Bundle Size Report

Package dist + ESM entry

Bundle targets

Consumer scenarios

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

changeset-bot bot commented Mar 13, 2026 •

edited

Loading

netlify bot commented Mar 13, 2026 •

edited

Loading

pkg-pr-new bot commented Mar 13, 2026 •

edited

Loading

github-actions bot commented Mar 13, 2026 •

edited

Loading