In a NestJS 12 app, why can OrdersService not inject PaymentsService from PaymentsModule until that module exports it?
answer
- modules encapsulate by default
- exports form the public API
- import the module, not the class
- imports are not transitive
basics
~10 sNest modules encapsulate their providers: OrdersModule can inject only its own providers and those an imported module lists in exports. Until PaymentsModule exports PaymentsService, bootstrap fails with a "Nest can't resolve dependencies" error.
solid answer
~30 sA `@Module()` declares `providers`, `imports` and `exports`, and a provider is visible outside its host module only when that module lists it in `exports`. So `PaymentsModule` must export `PaymentsService` and `OrdersModule` must import `PaymentsModule`; every importer then shares one instance. With either half missing, Nest stops at bootstrap with `Nest can't resolve dependencies of the OrdersService (?)`, naming the argument, its index and the module it searched. Adding `PaymentsService` to `OrdersModule`'s own `providers` is the wrong fix: it boots, but creates a second instance. Imports are not transitive, and `@Global()` only removes the import line; the provider must still be exported.
code
typescript · 29 linesimport { Injectable, Module } from '@nestjs/common';
@Injectable()
export class PaymentsService {
charge(orderId: string, cents: number) {
return { orderId, cents, status: 'captured' };
}
}
@Module({
providers: [PaymentsService],
exports: [PaymentsService], // without this line OrdersService cannot see it
})
export class PaymentsModule {}
@Injectable()
export class OrdersService {
constructor(private readonly payments: PaymentsService) {}
place(orderId: string) {
return this.payments.charge(orderId, 4200);
}
}
@Module({
imports: [PaymentsModule], // import the module, never re-list the service
providers: [OrdersService],
})
export class OrdersModule {}go deeper
Recall the four @Module() keys and the rule that only exported providers cross a module boundary; fix the error by exporting from the host module and importing that module.
Explain how the injector searches the current module, then imported modules' exports, then re-exported modules, and why re-registering a service creates a second instance.
Read an unresolved-dependency message precisely, tell a missing export from an import type or global-module mistake, and reach for NEST_DEBUG when the graph is large.
Treat exports as each module's public API: keep them small, reserve @Global() for genuine infrastructure, and use re-exporting core modules so feature modules stay decoupled.
## The three arrays that draw a module's boundary A NestJS **module** is a class decorated with `@Module()`. Nest starts from the root module and builds an **application graph** of modules and the **providers** (injectable classes and values) inside them. The decorator's metadata decides what each module may see: | Key | What it declares | Visible to | |---|---|---| | `providers` | classes and values the Nest injector creates in this module | this module only, by default | | `imports` | other modules whose exported providers this module needs | this module | | `exports` | the subset of `providers` (by class or token), or imported modules, offered to importers | every module that imports this one | | `controllers` | the controllers this module instantiates | this module | The documentation's rule is short: a module **encapsulates** its providers, and you can inject only providers that belong to the current module or that an imported module **explicitly exports**. A module's exports are its public API; everything else is private. ## What the injector does when OrdersService asks for PaymentsService When Nest instantiates `OrdersService`, it reads the constructor's parameter types and looks each one up: 1. In the providers of the module that hosts `OrdersService` (`OrdersModule`). 2. In each module listed in `OrdersModule`'s `imports`, accepting a match only when that module both provides **and exports** the token. 3. Through modules that an imported module **re-exports**, and no further: a module that `PaymentsModule` merely imports is not searched. If nothing matches, bootstrap stops with `UnknownDependenciesException`. In NestJS 12, a missing export produces: ```plaintext Nest can't resolve dependencies of the OrdersService (?). Please make sure that the argument PaymentsService at index [0] is available in the OrdersModule module. ``` The `?` marks the unresolved position. The message then lists likely causes: the provider is not part of the module, or the module that exports it is not imported. A different hint appears when the parameter type was `undefined` at runtime, which commonly comes from `import type` erasing the class. ## Right fixes and wrong ones The fix has two halves, and both are needed: - `PaymentsModule` lists `PaymentsService` in `exports` (it must also be in its `providers`). - `OrdersModule` lists `PaymentsModule`, the module rather than the service class, in `imports`. Fixes that look tempting and are wrong: - **Re-registering the service.** Adding `PaymentsService` to `OrdersModule`'s `providers` usually makes the error go away, but each module then gets its own instance. Any state the service holds is split, and its own dependencies must now be resolvable inside `OrdersModule` too. - **`@Global()` without `exports`.** A global module is bound into every other module's imports automatically, so consumers skip the `imports` line, but the injector still sees only what the global module exports. - **Exporting what you do not provide.** Listing `PaymentsService` in `exports` but not in `providers` fails at bootstrap with `UnknownExportException` ("Nest cannot export a provider/module that is not a part of the currently processed module"). - **Relying on the root module.** `AppModule` importing both feature modules does not make them see each other; visibility follows each module's own `imports`. ## Imports are not transitive If `PaymentsModule` imports a `BillingModule` that exports `BillingService`, `OrdersModule` still cannot inject `BillingService` by importing `PaymentsModule`. Either `OrdersModule` imports `BillingModule` itself, or `PaymentsModule` **re-exports** it by listing `BillingModule` in its own `exports`. Re-exporting is how a core module bundles shared modules for the rest of the app. ## Why Nest enforces the boundary Encapsulation is what keeps a large module graph manageable. A module's `exports` act as a contract: other modules depend on that list, not on whatever happens to sit in `providers`. A team can add, rename or split internal providers of `PaymentsModule` without touching `OrdersModule`, as long as the exported API stays the same. The bootstrap error is the price: Nest refuses to guess which instance you meant and stops before the app starts serving traffic, rather than failing on the first request. ## Diagnosing a resolution error - Read the message literally: the class being built, the `?` position, the argument name and the module Nest searched. - Check that the module named in the message imports the module that exports the dependency. - Set the `NEST_DEBUG` environment variable for extra resolution logs during startup; they show which modules the injector looked in. - Remember that a module class itself cannot be injected as a provider, and that providers in a module are singletons shared by every importer unless a scope says otherwise.
- PaymentsModule imports a BillingModule that exports BillingService. Can OrdersModule, which imports only PaymentsModule, inject BillingService?No. Imports are not transitive: OrdersModule sees only what PaymentsModule itself exports. PaymentsModule can re-export BillingModule by listing it in its own `exports`, after which every importer of PaymentsModule can inject BillingService; otherwise OrdersModule imports BillingModule directly.
- Does decorating PaymentsModule with @Global() remove the need for the exports array?No. `@Global()` makes Nest add the module to every other module's imports, so consumers drop the import line, but lookup still accepts only exported providers. A global module with no `exports` fails with the same resolution error. Register a global module once, typically from the root or a core module, and use it sparingly.
- What happens if PaymentsModule lists PaymentsService in exports but not in providers?Bootstrap fails with `UnknownExportException`, whose message says Nest cannot export a provider or module that is not part of the module being processed. A module may export only its own providers, by class or token, or modules it imports.
A module is a department with a public service desk: other departments that have signed an agreement (imports) can use the services posted at the desk (exports), never the staff working in the back office.
- Re-registering PaymentsService in OrdersModule's providers shares the same instance.
- Importing a module makes every one of its providers injectable.
- @Global() exposes all of a module's providers, even without exports.
- If AppModule imports both modules, they can inject each other's providers.
- Importing PaymentsModule also exposes everything PaymentsModule imports.