Debugging

Resolving common NestJS dependency injection, token, circular dependency, and scope issues.

Cannot resolve dependency

Symptom: Nest can't resolve dependencies of the X (?)... Please make sure that the dependency is available in the current Module context.

Typical causes: a provider missing from providers, an unexported provider from an imported module, or a wrong module import.

Mitigation: confirm the error names the host class, the missing token, and the module context; add or export the provider; verify dynamic module imports return the expected surface.

For verbose injection traces during development, run with Nest’s debug logging for the DI explorer (see current Nest CLI and documentation for the supported environment flag in your version).

Interface and metadata pitfalls

TypeScript interfaces do not exist at runtime, so they cannot be injection tokens. Prefer a class, a symbol, or a string constant with @Inject. If the error message refers to Object or an unhelpful token, suspect a missing @Inject or emitDecoratorMetadata misconfiguration for class-based implicit injection.

Circular dependencies

Symptom: startup fails with circular import or provider resolution loops.

Mitigation: extract shared types and constants to neutral modules; keep module import graphs acyclic; use forwardRef() only as a last resort after restructuring. Dependency graph tools (for example madge) help locate import cycles in compiled output.

Scope surprises

If instances are not singletons when expected (or the opposite), trace scope bubbling: a singleton that depends on a request-scoped provider becomes request-scoped. Verify @Injectable({ scope: ... }) and registration sites; prefer explicit scope on public services when the team shares ownership of the module.

General techniques

Raise logger verbosity during investigation.
Inspect emitted JavaScript when metadata or path aliases behave unexpectedly.
Use ModuleRef.get / resolve sparingly for debugging container contents in non-production code paths.

Dependency injection — tokens, scopes, and sub-trees.
Extensibility and tooling — discovery and dynamic modules.