INCIDENT RUNBOOK

Fix: Unhandled Cold Start Sigterm in Fastify on Docker

Comprehensive architectural post-mortem and verified configuration patch for fastify deployed in docker production environments.

Automated Remediation ProtocolUpdated for 2026 Production

Facing unhandled-cold-start-sigterm in CI/CD or runtime containers?

Review the verified configuration patches below. To automate incident triage and fine-tune your own internal agents, check out our production AI training datasets.

🧠 Explore Security & Code Datasets →All Runtime Fixes →

● Observed Terminal Error / Stack Trace

Error: Server did not shut down in time. Received SIGTERM
    at /app/node_modules/fastify/lib/server.js:391:13
    at processTicksAndRejections (internal/process/task_queues.js:95:5)
    at async Server.close (/app/node_modules/fastify/lib/server.js:373:5)
    at async DockerContainer.shutdown (/app/node_modules/docker-container.js:123:10)

Root Cause Analysis

The error occurs due to a mismatch between the Docker container's shutdown signal handling and Fastify's internal process termination mechanism. When a Docker container receives a SIGTERM signal, it expects the process to terminate gracefully within a certain timeframe. However, Fastify's cold start mechanism, which involves loading and initializing the application, can take longer than this timeframe, leading to an unhandled SIGTERM signal. This incompatibility causes the container to be forcefully terminated, resulting in an unhandled cold start SIGTERM error.

● Configuration & Code Resolution

To resolve this issue, update the Docker configuration to increase the shutdown timeout and modify the Fastify configuration to handle SIGTERM signals explicitly. Add the following configuration to your docker-compose.yml file:

version: '3'
services:
  app:
   ...
    stop_grace_period: 10m

And update your Fastify application to handle SIGTERM signals:

const fastify = require('fastify')({
  //...
  ignoreTrailingSlash: true,
  disableRequestLogging: true
})

process.on('SIGTERM', () => {
  console.log('Received SIGTERM, shutting down...')
  fastify.close().then(() => {
    console.log('Fastify server closed')
    process.exit(0)
  })
})

Verification & Build Command

docker-compose up --build && curl -X GET http://localhost:3000 && docker-compose down