skip to content

Module Graph & Providers

Modules declare providers, imports and exports; the injector resolves constructor tokens, custom providers and request or transient scope. Interviewers ask why an unexported provider fails to resolve.

on this pageshow

explore

questions

6

In a NestJS 12 app, why can OrdersService not inject PaymentsService from PaymentsModule until that module exports it?

level: juniorimportance: must knowfreq 80%

answer

  1. modules encapsulate by default
  2. exports form the public API
  3. import the module, not the class
  4. imports are not transitive

basics

~10 s

Nest 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 s

A `@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 lines
typescript
import { 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

for a junior

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.

for a middle

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.

for a senior

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.

for a principal

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.
open as a page

In NestJS, how do useClass, useValue, useFactory and useExisting providers differ, and when must a consumer use @Inject() with a token?

level: middleimportance: must knowfreq 65%

basics

~20 s

Each NestJS custom provider maps a token to a value: useClass instantiates a class, useValue registers a ready object, useFactory returns what a function builds from its inject list, and useExisting aliases another token. Non-class tokens need @Inject(token).

open as a page

In NestJS, what is a dynamic module returned by forRoot() or register(), and what does ConfigurableModuleBuilder generate for you?

level: middleimportance: should knowfreq 40%

basics

~20 s

A NestJS dynamic module is a DynamicModule object, @Module metadata plus a required module key, that a static method builds from the caller's options. ConfigurableModuleBuilder generates that method, its Async variant and the options token.

open as a page

In a NestJS app, OrdersService and PaymentsService inject each other and bootstrap fails. What does Nest report, and how does forwardRef() resolve it?

level: seniorimportance: should knowfreq 50%

basics

~20 s

NestJS reports a CircularDependencyException, or an undefined dependency at some index when a file-level import cycle hides a class. Wrapping each side's token in @Inject(forwardRef(() => Other)) lets Nest resolve both; module cycles use forwardRef() in imports.

open as a page

In a NestJS app, a per-tenant connection provider is marked Scope.REQUEST and every endpoint that reaches it gets slower. Why, and what can replace it?

level: seniorimportance: should knowfreq 45%

basics

~20 s

In NestJS, Scope.REQUEST bubbles up the injection chain: every provider and controller that depends on the tenant connection becomes request-scoped and is rebuilt per request. Durable providers or a singleton reading tenant context avoid that.

open as a page

After upgrading to NestJS 12, why does a subclass provider that redeclares its constructor fail with UnknownDependenciesException where its parent's @Optional() used to apply?

level: seniorimportance: nice to knowfreq 15%

basics

~20 s

NestJS 12 reads @Optional() markers from the class that declares the constructor, not up the prototype chain. A subclass that redeclares its constructor without its own @Optional() makes the missing token a hard error instead of undefined.

open as a page