DI containers in production: resolution graphs, circular deps, and when not to

An app boots fine in development and crashes on the production server with Nest can't resolve dependencies of the UserService (?, AuthService). Nothing about UserService changed. What changed is that AuthService now imports UserService, and UserService already imported AuthService — a cycle. In dev the modules happened to load in an order that papered over it; in prod they did not. The container is not buggy. It is telling you it cannot put a circle in a line.

A container is a graph resolver

Strip away the decorators and a DI container does one thing: it reads the dependency declarations, builds a directed graph, and instantiates in dependency order — leaves first, then the things that depend on them, up to the root. This is a topological sort. To create OrderService(db, payments), it must first create db and payments; to create those it resolves their dependencies, recursively. For singletons it does this once and caches the instance, so the second consumer of db gets the same object. The container is the automated composition root from earlier in the unit — the one place that knows concretions, now mechanized.

Why circular dependencies break it

A topological sort only exists for a directed acyclic graph. If A depends on B and B depends on A, there is no “leaves first” order: to build A you need B, but to build B you need A. The container detects the cycle and refuses, which is the Hook’s error. Frameworks offer an escape hatch — NestJS’s forwardRef(() => Other) — that breaks the deadlock by deferring one side’s resolution until after construction. But the escape hatch is a smell, not a solution: a cycle almost always means two classes that should be one, or a missing third class that both should depend on. Reaching for forwardRef to silence the error preserves the design flaw.

Eager vs lazy: when failure surfaces

Containers differ on when they instantiate. Eager instantiation builds the whole singleton graph at startup, before serving traffic — NestJS does this by default. Lazy instantiation creates each provider on first use. The tradeoff is when bad configuration bites: eager startup means a missing env var or unresolvable dependency crashes the boot — loud, immediate, before any user is affected. Lazy means the same misconfiguration hides until the first request hits that code path, possibly hours later, possibly only on one endpoint. For server applications the senior preference is overwhelmingly eager: pay a slightly slower boot to convert a 3 a.m. runtime page into a deploy-time failure your CI catches.

The hidden costs

A container is not free. It adds startup time (building the graph), a learning and debugging tax (stack traces run through framework resolution code, and “cannot resolve” errors are their own skill to read), and a temptation toward hidden global state — the container becomes a place to stash singletons that are really just globals with extra steps. For a small service, a CLI, or a serverless function with a tiny graph, hand-wiring in a composition root — plain new calls in one file at the entry point — is often clearer and faster than a container. The container earns its cost when the graph is large, lifetimes are mixed, and the wiring would otherwise be a sprawling manual mess. “Use a DI container” is a scale decision, not a default.