INCIDENT RUNBOOK

Fix: Unhandled Cold Start Sigterm in Fastify on Vercel

Comprehensive architectural post-mortem and verified configuration patch for fastify deployed in vercel 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 [ERR_SERVER_NOT_RUNNING]: Server is not running at Error_NATIVE (native)
    at Object.onceWrapper (events.js:520:26)
    at Server.emit (events.js:412:35)
    at emitCloseNT (net.js:1677:8)
    at processTicksAndRejections (internal/process/task_queues.js:83:21)
    at runNextTicks (internal/process/task_queues.js:65:3)
    at listOnTimeout (internal/timers.js:487:11)
    at processTimers (internal/timers.js:431:7)

Root Cause Analysis

The unhandled-cold-start-sigterm error occurs due to a runtime incompatibility between Fastify's serverless mode and Vercel's serverless functions. When a cold start happens, Vercel sends a SIGTERM signal to the serverless function to terminate it after a period of inactivity. However, Fastify's serverless mode does not handle this signal by default, leading to an unhandled exception. This is because Fastify is designed to handle HTTP requests, not signals. To fix this issue, we need to configure Fastify to handle the SIGTERM signal and properly shut down the server.

● Configuration & Code Resolution

To fix this issue, add the following configuration to your `vercel.json` file:
{
  "version": 2,
  "functions": {
    "api/**/*.js": {
      "memory": 128,
      "maxDuration": 5
    }
  }
}
And add the following code to your Fastify server:
javascript
const fastify = require('fastify')({
  logger: true
})

process.on('SIGTERM', () => {
  fastify.server.close(() => {
    process.exit(0)
  })
})

Verification & Build Command

Run the following command to verify the resolution: `vercel dev --port 3000` and then send a request to `http://localhost:3000/api/healthcheck` after a few minutes of inactivity to test the cold start behavior.