INCIDENT RUNBOOK

Fix: Unhandled Cold Start Sigterm in Astro on Cloudflare Workers

Comprehensive architectural post-mortem and verified configuration patch for astro deployed in cloudflare workers 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_WORKER_TERMINATED]: Worker terminated due to SIGTERM signal
    at Worker._terminate (/usr/local/lib/node_modules/@cloudflare/wrangler/dist/src/worker.js:155:23)
    at process.<anonymous> (/usr/local/lib/node_modules/@cloudflare/wrangler/dist/src/worker.js:173:9)
    at process.emit (events.js:314:20)
    at process.emit (domain.js:482:12)
    at Worker.emit (events.js:314:20)
    at Worker._handleMessage (/usr/local/lib/node_modules/@cloudflare/wrangler/dist/src/worker.js:128:10)

Root Cause Analysis

The error occurs due to Cloudflare Workers' cold start behavior, where the worker is terminated after a period of inactivity. Astro, being a server-side rendered framework, doesn't handle this termination signal by default, resulting in an unhandled SIGTERM error. This incompatibility arises from the difference in design principles between Astro's server-side rendering and Cloudflare Workers' edge computing model.

● Configuration & Code Resolution

Add the following configuration to your `wrangler.toml` file:

[[mimeType]]
  wildcard = "*"
  contentType = "text/html"

[build]
  command = "npx astro build"
  output = "dist"

[env]
  GENERAL_NODE_ENV = "production"

And add the following code to your `astro.config.js` file:

export default {
  //...
  renderMode: 'server',
  //...
};

Then, update your `worker.js` file to handle the SIGTERM signal:

import { handleRequest } from './src/entry-server.js';

self.addEventListener('SIGTERM', () => {
  console.log('Worker terminated due to SIGTERM signal');
});

addEventListener('fetch', (event) => {
  event.respondWith(handleRequest(event.request));
});

Verification & Build Command

Run `npx wrangler publish` to deploy your Astro application to Cloudflare Workers, then use `npx wrangler tail` to verify that the SIGTERM signal is handled correctly and the application doesn't crash due to cold start