NestJS graceful shutdown limits with async guards during module replacement

Direct answer

NestJS does not impose a specific draining limit on requests when app.close() is called during an active async guard. The framework stops accepting new connections and allows the current request‑processing pipeline to finish; the actual timeout is controlled by the underlying HTTP adapter (Express or Fastify) and any process‑level shutdown timeout you configure.

Confirmed facts

• Graceful shutdown is handled via enableShutdownHooks() and app.close(). NestJS stops listening for new connections and lets in‑flight requests complete.
• There is no documented guard‑specific request‑draining limit or timeout.
• Modules and providers are instantiated at bootstrap; dynamic modules are a configuration‑time feature, not a documented runtime hot‑swap mechanism.
• Async guard execution and shutdown hook behavior have been stable across NestJS major versions for standard use.

Likely explanation

When app.close() is invoked:

1. The HTTP server stops accepting new sockets.
2. Each existing socket continues through the request lifecycle, including any CanActivate guard that has already started.
3. The guard’s async/await chain runs to completion because Nest does not cancel the promise; the request finishes normally.
4. If a module that supplies a guard is replaced while a request is in flight, the request retains the guard instance that was resolved at the start of that request. New requests after the swap will resolve the new instance.
5. This can lead to inconsistent execution context or lost request‑scoped dependencies, but Nest does not guarantee preservation across a runtime module swap.

Steps to verify your setup

1. Identify the HTTP adapter in use (Express or Fastify) and whether you have set a shutdown timeout via enableShutdownHooks({ stopLoadingNewConnections: true, shutdownTimeout: ... }) or directly on the server.
2. Check for any custom logic that uses ModuleRef or similar to replace providers/guards at runtime.
3. Confirm the NestJS major version you are running (e.g., 9.x, 10.x).
4. Run a controlled test: send a request that triggers a long‑running async guard, then issue SIGTERM (or call app.close()) and observe whether the request completes and whether new requests are rejected.

Missing diagnostic detail

Do you have a custom shutdown timeout configured (via enableShutdownHooks or the HTTP server)? Knowing this changes whether you need to adjust the timeout to accommodate long‑running guards.