Skip to content

fix(core): roll back modules on failed lazy load - #18385

Merged
kamilmysliwiec merged 3 commits into
nestjs:masterfrom
Asadshah7950:fix/lazy-module-loader-failed-load-rollback
Nov 6, 2026
Merged

kamilmysliwiec merged 3 commits into
nestjs:masterfrom
Asadshah7950:fix/lazy-module-loader-failed-load-rollback

Conversation

@Asadshah7950

Copy link
Copy Markdown
Contributor

Follow-up to #18183 and #18371.

PR Checklist

Please check if your PR fulfills the following requirements:

PR Type

What kind of change does this PR introduce?

  • Bugfix
  • Feature
  • Code style update (formatting, local variables)
  • Refactoring (no functional changes, no api changes)
  • Build related changes
  • CI related changes
  • Other... Please describe:

What is the current behavior?

When a provider of a lazily loaded module throws during load() (or when scanning encounters an invalid/undefined import), LazyModuleLoader.load() rejects, but leaves the partially constructed module registered in NestContainer.

Because createPrototypes() marks the module class instantiated before resolving providers, Module#isInstantiated is already true. On any subsequent load(), scanForModules() sees lazy && !moduleInserted && moduleInstance?.isInstantiated, returns [], and load() hands back the broken ModuleRef whose failed providers hold null / uninstantiated state. The module never heals.

If the failing module is @Global(), it also permanently remains in globalModules, causing subsequent lazy modules to bind to the dead global instance.

In #18183, @kamilmysliwiec noted that a safe rollback required two things:

  1. Concurrent load() calls of the same module sharing a single in-flight load (which was merged in fix(core): share one in-flight load between concurrent lazy loads #18371).
  2. Targeted cleanup that only removes what the failed load itself added, with an identity check in removeModules() so late rollbacks never delete modules rebuilt by retries or owned by concurrent successful loads.

Issue Number: N/A

What is the new behavior?

  1. Scan failure rollback: In LazyModuleLoader.load(), scanning is wrapped in a try/catch. Newly inserted modules are tracked during the scan; if scanning throws midway (e.g. an undefined or invalid nested import), any modules inserted during that scan are cleanly removed via DependenciesScanner.removeModules().
  2. Build failure rollback: If buildModules fails during createInstancesOfDependencies() or dependency scanning, modulesToBuild (the modules this load was responsible for building) are removed via DependenciesScanner.removeModules(modulesToBuild).
  3. Identity check on removal: In NestContainer.removeModules(), an identity check if (this.modules.get(moduleRef.token) !== moduleRef) continue; ensures we only delete if the module stored in the container is the exact instance being rolled back. This prevents late rollbacks from deleting a retry that already succeeded.
  4. Metadata host cleanup: DiscoverableMetaHostCollection.removeInstanceWrappers() cleans up discovery entries for both providers and controllers by instance wrapper ID.
  5. Preserving concurrent modules: Concurrent loads sharing dependencies (e.g. AModule and BModule both importing SharedModule where A fails and B succeeds) do not evict modules owned by another load.

Does this PR introduce a breaking change?

  • Yes
  • No

The public API only adds NestContainer.removeModules(), DependenciesScanner.removeModules(), and DiscoverableMetaHostCollection.removeInstanceWrappers().

Other information

  • Unit tests added covering:
    • Module rebuilds and re-executes provider factory on subsequent load() after first failed.
    • Global module rebuilds and re-registers cleanly with subsequent consumer loads.
    • Scan failure rollback when an import is undefined.
    • Concurrent loads sharing a dependency where one fails and one succeeds.
    • Immediate retry of a failed module while another load importing it was in-flight.
    • NestContainer.removeModules clears global, dynamic, provider discovery, and controller discovery entries, and ignores mismatched tokens.
  • All unit and integration test suites pass (vitest run packages/core/test/injector, vitest run packages/core/test/discovery, vitest run --config vitest.config.integration.mts integration/lazy-modules).

When a provider of a lazily loaded module fails during instantiation or scanning encounters an error, load() previously left half-built modules registered in NestContainer. Subsequent load() calls returned the broken ModuleRef.

Following up on nestjs#18371 (in-flight deduplication), safely roll back failed loads:
- Track inserted modules during lazy scan and roll them back if scanning throws.
- Roll back modulesToBuild if buildModules rejects.
- Use identity check in NestContainer.removeModules to avoid clobbering concurrent or retried instances.
- Remove provider and controller metadata entries in DiscoverableMetaHostCollection.

@agammann agammann left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

A failed dynamic import can leave the parent module in the container, so this rollback does not make the next lazy load retryable. setModule() calls this.modules.set(token, moduleRef) and then awaits addDynamicMetadata() (which recursively calls addDynamicModules()); addModule() pushes moduleRef into insertedModules only after that await returns. If an imported dynamic module fails to compile/insert, the parent was inserted but never added to the rollback list, so scanForModules() catches the error and removes only the children. A subsequent load() sees the leftover parent as already present. Please register the parent for rollback immediately after this.modules.set, or remove it in setModule when dynamic metadata insertion rejects; a failing dynamic imports case would cover this path.

@kamilmysliwiec kamilmysliwiec left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Thanks for picking this up. A few things need to change before this can be reviewed in depth:

  1. It doesn't build. packages/core/scanner.ts:617: TS2554: Expected 3 arguments, but got 4. insertOrOverrideModule() passes insertedModules to overrideModule(), which still takes three.
  2. Overridden modules aren't tracked. NestContainer#replaceModule() gains an insertedModules parameter but never uses it: it doesn't pass it to setModule() and doesn't record the module. A module replaced through overrideModule() (e.g. in a testing module) that fails to load is therefore left registered, which is the case this PR sets out to fix.
  3. Global modules bound in the meantime. Removing a failed @Global() module from globalModules doesn't undo bindGlobalsToImports(). A module that another load() scanned while this one was in flight keeps the removed module in its imports. Rolling back has to unlink it from every module it was bound to, or the global modules have to be bound only once the load succeeded.
  4. Unrelated changes. The NestContainer constructor is reformatted (likely a different Prettier version); please run the repository's npm run format so the diff only holds the fix.

Once it builds, the tests also need to cover points 2 and 3: a failed load of an overridden module, and a failed global module next to a concurrent load of another module.

)

- Fix scanner.overrideModule signature and forward insertedModules to replaceModule.
- Track inserted module in setModule immediately and clean up on dynamic metadata error.
- Unlink rolled-back modules from module.imports across remaining modules.
- Revert unrelated constructor formatting diff in NestContainer.
- Add unit tests covering overridden modules, concurrent globals, and dynamic import failures.
@Asadshah7950

Copy link
Copy Markdown
Contributor Author

Hi @kamilmysliwiec, @agammann,

Thank you both for the detailed and constructive reviews! I've addressed all points in the latest commit:

  1. Build failure & signature (scanner.ts):

    • Added insertedModules?: Module[] to DependenciesScanner#overrideModule() and forwarded it to container.replaceModule(). Cleaned up the call in insertOrOverrideModule().
      pm run build now compiles cleanly across all packages.
  2. Tracking overridden modules (
    eplaceModule)
    :

    • Passed insertedModules down to his.setModule() in NestContainer#replaceModule().
    • Added a unit test verifying that when an overridden module's provider throws during lazy loading, the overridden module is cleanly rolled back and subsequent loads succeed.
  3. Global module unlinking (
    emoveModules)
    :

    • In NestContainer#removeModules(), added his.modules.forEach(module => module.imports.delete(moduleRef)) so rolled-back modules (including failed @global() modules) are unlinked from the imports set of any other concurrently loaded modules.
    • Added a unit test validating concurrent lazy loads where a @global() module fails while another module loads, confirming the remaining module does not retain the failed module in its imports.
  4. Dynamic imports rollback (noted by @agammann):

    • Moved insertedModules?.push(moduleRef) in setModule() right after his.modules.set(token, moduleRef) (before awaiting �ddDynamicMetadata()), and wrapped �ddDynamicMetadata() in a ry/catch that cleans up his.modules and his.dynamicModulesMetadata on error.
    • Added a unit test verifying that if an imported dynamic module fails to evaluate, the parent module is cleanly rolled back and not left in NestContainer.
  5. Constructor formatting:

    • Restored NestContainer constructor layout to match upstream/master exactly, keeping the PR diff minimal and focused.

@kamilmysliwiec kamilmysliwiec left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Thanks, this covers everything from the last round. Two small things are left:

  1. A slow sibling can outlive the rollback. addDynamicModules() still uses Promise.all(). If a dynamic module's imports hold one import that rejects and one that is still pending (a slow import(), say), the load rolls back as soon as the first one rejects. The pending one then reaches setModule() and stays in the container, because it's pushed to insertedModules after removeModules() has already read the list.

    Please wait for all of them with Promise.allSettled() and rethrow the first rejection, so that every sibling is tracked before the rollback. A test for it: a dynamic module with imports: [Promise.reject(err), slowPromise], expecting an empty container once the slow import has resolved.

  2. The try/catch in setModule() is no longer needed. The parent is now in insertedModules before the await, so removeModules() already removes it. With the catch in place, removeModules() skips that module instead, because its token no longer maps to it. Dropping the catch also leaves the bootstrap path as it is on master.

…setModule try-catch (nestjs#18385)

- Use Promise.allSettled() in addDynamicModules() so pending siblings are tracked before throwing rejection.
- Drop try/catch in setModule() since parent is registered in insertedModules and cleanly removed by removeModules().
- Add unit test for dynamic imports with slow sibling.
@Asadshah7950

Copy link
Copy Markdown
Contributor Author

Hi @kamilmysliwiec,

Thanks for the great feedback! Both points have been updated in the latest commit:

  1. Slow sibling dynamic imports (�ddDynamicModules):

    • Replaced Promise.all() with Promise.allSettled() in NestContainer#addDynamicModules(), rethrowing the first rejection only after all siblings have settled so all inserted modules are tracked before rollback runs.
    • Added a unit test with mixed dynamic imports [Promise.reject(err), slowPromise] verifying that once the slow import resolves, the container remains completely empty.
  2. Removed redundant ry/catch in setModule():

    • Dropped the ry/catch block around �ddDynamicMetadata(). Since insertedModules?.push(moduleRef) runs before the �wait,
      emoveModules() cleans up the parent module and unlinks it without skipping, leaving the bootstrap path unchanged from master.

@kamilmysliwiec
kamilmysliwiec merged commit 0fd8642 into nestjs:master Nov 6, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants