Timeouts Everywhere

Set timeouts on server requests, outbound HTTP, database queries, and queues - unbounded waits are the most common cause of cascading Node.js API outages.

Recipe

Quick-reference recipe card - copy-paste ready.

import { createServer } from "node:http";
 
const server = createServer(app);
server.requestTimeout = 30_000;
server.headersTimeout = 35_000;
server.keepAliveTimeout = 65_000;
 
const data = await fetch(url, { signal: AbortSignal.timeout(5_000) });

When to reach for this:

• p99 latency spikes with flat CPU (threads waiting, not working).
• Connection pool exhausted under moderate load.
• Load balancer 502/504 during downstream slowness.
• Any fetch or axios call without explicit timeout.

Working Example

import express from "express";
import { createServer } from "node:http";
import pg from "pg";
 
const pool = new pg.Pool({
  connectionString: process.env.DATABASE_URL,
  connectionTimeoutMillis: 3_000,
  query_timeout: 5_000, // node-pg option wrapping statement timeout
});
 
const app = express();
 
app.get("/reports/:id", async (req, res) => {
  const controller = AbortController ? new AbortController() : null;
  const deadline = setTimeout(() => controller?.abort(), 8_000);
 
  try {
    const report = await pool.query(
      "SELECT * FROM reports WHERE id = $1",
      [req.params.id]
    );
 
    const enrichment = await fetch(
      `https://analytics.internal/enrich/${req.params.id}`,
      { signal: controller?.signal ?? AbortSignal.timeout(8_000) }
    );
 
    if (!enrichment.ok) {
      return res.status(502).json({ error: "Analytics unavailable" });
    }
 
    res.json({ report: report.rows[0], analytics: await enrichment.json() });
  } catch (err) {
    if ((err as Error).name === "AbortError") {
      return res.status(504).json({ error: "Upstream timeout" });
    }
    throw err;
  } finally {
    clearTimeout(deadline);
  }
});
 
const server = createServer(app);
server.requestTimeout = 30_000;
server.listen(3000);

What this demonstrates:

• DB pool connection timeout vs query timeout - different failure modes.
• Outbound fetch bounded to 8s - less than server 30s request timeout.
• AbortError mapped to 504 Gateway Timeout for clients.
• createServer timeouts protect against slowloris and hung sockets.

Deep Dive

How It Works

• Server requestTimeout - max time for full request on socket (Node HTTP server).
• AbortSignal.timeout - aborts fetch after N ms in Node 18+.
• statement_timeout (Postgres) - DB kills long queries regardless of app state.
• Timeouts should cascade: outbound < handler deadline < server < load balancer.

Timeout Budget Table

Postgres statement_timeout

SET statement_timeout = '5s';
-- or per role:
ALTER ROLE app_user SET statement_timeout = '5s';

await pool.query("SET statement_timeout = 5000");

• Server-side kill prevents one bad query from holding connections forever.

Axios Equivalent

import axios from "axios";
 
const client = axios.create({ timeout: 5_000 });

• timeout covers connection + response; use signal: AbortSignal.timeout() for finer control.

Gotchas

• No timeout on fetch - waits until LB kills - pool exhaustion. Fix: always AbortSignal.timeout.
• Same timeout all layers - race between LB and app 502. Fix: stagger budgets.
• Retry without timeout reduction - amplifies load. Fix: shorter per-attempt timeout.
• Ignoring headersTimeout - must exceed keepAliveTimeout slightly on Node HTTP server.
• Long transactions without statement_timeout - holds pool connections. Fix: DB-level limit.
• Timeout only in happy path - clear timers in finally. Fix: avoid leaked handles.

Alternatives

FAQs

Related

• Resilience Basics - introductory patterns
• Retries with Backoff - per-attempt timeouts
• Circuit Breakers - fail fast when downstream sick
• Performance on Express - server timeout tuning

External Related Links

• Node.js Best Practices (GitHub) - Curated production best practices.
• Node.js API Documentation - Complete reference for core modules and APIs.
• DigitalOcean Node.js Tutorials - Production-oriented how-tos.
• Distributed Systems with Node.js - Enterprise-ready distributed systems.
• Node.js Cookbook, 5th Edition - Practical server-side recipes.

Stack versions: This page was written for Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5, and NestJS 11.