Lifecycle hooks and graceful shutdown

Init: bottom-up, child modules before parents

When you ask “can I start a poller in onModuleInit?” or “why did my sibling module’s connection look unready?”, the answer comes down to the boot order. Get it right and your startup is deterministic; get it wrong and you fire into a half-initialized graph.

Nest boots in two passes. First it constructs the whole DI graph — every provider that L02 taught you about. Then it walks the modules and fires the init hooks. Two hooks matter here, and the order between them is the thing people get wrong.

onModuleInit() fires per module, as soon as that module’s own providers are resolved — and children (imported modules) fire before their parents. So a DatabaseModule you import runs its onModuleInit before the UsersModule that imports it. onApplicationBootstrap() fires once, after every module in the app has finished initializing.

import { Injectable, OnModuleInit, OnApplicationBootstrap } from '@nestjs/common';

@Injectable()
export class IndexerService implements OnModuleInit, OnApplicationBootstrap {
  // runs when THIS module's providers are ready — children before parents.
  // Hooks may be async; Nest awaits them before moving on.
  async onModuleInit() {
    await this.warmLocalCache(); // only needs THIS module's deps
  }

  // runs after the ENTIRE app graph is live — safe to touch other modules.
  async onApplicationBootstrap() {
    this.startPoller(); // depends on a sibling module being initialized too
  }
}

The distinction is not cosmetic. In onModuleInit of module A, the only thing guaranteed ready is A and the modules A imports. A sibling module B you reach across to — say a message bus you publish to — may not have run its own onModuleInit yet. Start a poller there and it can fire into a half-initialized graph.

Shutdown: reverse order, and OFF by default

Shutdown runs the lifecycle backwards. The order is onModuleDestroy() → beforeApplicationShutdown(signal?) → onApplicationShutdown(signal?), and modules tear down in reverse of init: dependents before dependencies. That ordering is deliberate — a module gets to clean up before the modules it depends on disappear, so your UsersModule can flush before the DatabaseModule it builds on closes its pool. The last two hooks receive the signal string ('SIGTERM', 'SIGINT') so you can branch on why you’re shutting down.

import { Injectable, OnModuleDestroy } from '@nestjs/common';
import { Pool } from 'pg';

@Injectable()
export class Database implements OnModuleDestroy {
  private pool = new Pool(/* ... */);

  // Nest AWAITS this on shutdown — drain in-flight, then close cleanly.
  async onModuleDestroy() {
    await this.pool.end(); // waits for active queries, then releases sockets
    // for a broker: await this.consumer.disconnect() — commit offsets, unsubscribe
  }
}

Here is the trap that produced the incident. None of these hooks run by default. Nest does not listen for OS termination signals unless you opt in — because registering process-level signal listeners has a small per-listener cost, and the framework refuses to impose it on every app silently. You enable it with one line in main.ts:

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  // WITHOUT this line, SIGTERM exits the process immediately and NO
  // onModuleDestroy / onApplicationShutdown ever runs — pools severed,
  // requests dropped, broker offsets uncommitted.
  app.enableShutdownHooks();

  await app.listen(3000);
}
bootstrap();

Forget that line and SIGTERM behaves like kill -9 as far as your cleanup is concerned: the event loop never gets a chance to run your pool.end(), the consumer never disconnects, and Kubernetes happily reports a successful rollout while the old pods leak half-finished work.

The two failure modes: no drain, and a drain that never ends

The first failure mode is the incident above: no enableShutdownHooks(), so SIGTERM truncates everything. The fix is the one line plus real cleanup in onModuleDestroy — await pool.end(), await consumer.disconnect() — so pools drain and the broker commits before the process leaves.

But there’s a symmetric second failure mode, and seniors hit it after they enable hooks: a shutdown hook that hangs. If onModuleDestroy awaits a promise that never resolves, or you write a 60-second drain, Kubernetes doesn’t wait forever. It waits terminationGracePeriodSeconds — default 30 seconds — then sends SIGKILL and truncates your cleanup anyway. A hook that blocks past the grace period is no safer than no hook at all; it just fails later and more confusingly. So the drain has to finish comfortably under 30 seconds: a sane budget is 5–15 seconds. And draining requests isn’t enough on its own — you also need the load balancer to stop sending new ones before you stop accepting. Flip the readiness probe to unready on SIGTERM and add a preStop sleep of about 5 seconds so endpoint deregistration propagates through kube-proxy before the app actually goes down. Otherwise you drain the old requests perfectly and then drop the new ones that arrived during the gap.