Diagnose construction failures, tokens and module visibility

Understand the likely causes

• Likely causes include an erased interface used as a token, a new Symbol instead of the exported one, omitted exports/imports, duplicate registrations, file cycles or invalid configuration in a resolved factory. Making every module global can hide one problem while changing ownership and creating unexpected resource lifetimes.

Locate the failing construction stage

Start with the safe error category and the smallest reproducible module graph. Determine whether the token was unknown, known but invisible, resolved with an unexpected scope, or constructed by a factory that later rejected. Preserve the exact requested token identity without logging credentials or configuration values. A test can instantiate providers during compile even before any controller method runs. Do not rerun full application startup against configured services merely to obtain a longer stack trace; isolate the graph with explicit fakes and retain the original failure metadata.

Compare the actual token and owner module

A TypeScript interface has no runtime token. For a symbol binding, compare the imported object, not its printed description. Then identify which module registers and exports that token and whether the consumer imports the owner. The JSON is a synthetic investigation note, not container output. Copying a provider into every consumer can create separate instances and pools rather than fixing visibility. If aliasing is intended, distinguish useExisting from constructing another implementation through useClass. Keep token declarations dependency-light so file cycles do not turn a valid name into an unavailable value during initialization.

{"requestedToken":"COURSE_READER-shared-runtime-object","owner":"CatalogModule","consumer":"ReportingModule","checks":["registered","exported","owner-imported","same-token-object","factory-stage"],"execution":"synthetic-review-only"}

Inspect configuration and resource initialization separately

Once inputs resolve, a factory can still fail while parsing configuration or obtaining a resource. Validate required text, numeric ranges and Boolean vocabulary before readiness, with safe setting-name diagnostics. Do not print secret values. Bound asynchronous startup and clean up resources already acquired if another dependency fails. Review whether request scope accidentally creates a source pool per caller. If the problem is a cycle, determine whether it belongs to file imports, modules or providers before applying forwardRef. A deferred reference is not a substitute for a clear domain owner or guaranteed hook order.

Compile a controlled graph and test its intended identity

In an authorized isolated project test, override the exact token before compile and supply a fake matching the service contract. Verify one intended shared instance, a negative visibility fixture and safe handling of invalid factory input. Then add only the next necessary real boundary. This editorial guide does not compile Nest or connect to a source; its JSON can be parsed locally. Record the exact package and runtime versions, because major-version module formats, optional constructor metadata and lifecycle rules can change. A passing diagram or string-name comparison is not container-resolution evidence.

Keep it from recurring

• Keep explicit module contracts, stable exported tokens and reviewed provider forms. Validate configuration centrally and avoid import-time operational effects. Retain focused container tests alongside pure domain tests so a future refactor cannot silently remove visibility or change instance sharing.