Node.js — Cannot set headers after they are sent to the client

What this error actually means

An HTTP response has a single header section. Once Node has committed that section to the outgoing response, a later attempt to change headers fails. The first write can commit implicit headers even when the code never called writeHead explicitly. A framework’s send, json or redirect usually makes that boundary less visible.

The stack trace points at the second attempt, but the first response is often where the ownership mistake began. A validation branch sends an error and continues; another branch later sends success. Alternatively, two asynchronous callbacks both believe they own completion. The fix is to make the terminal response path unique, not to suppress the exception at the later write.

headersSent and writableEnded describe different transitions. Headers may be sent while a streaming response is still open. Once streaming has begun, the application cannot replace the status with a JSON error response. It must follow the stream’s error contract, usually terminating an incomplete response and recording the failure.

How to diagnose it

rg -n "res\.(send|json|end|redirect|write|writeHead)|next\(" src

The fix

Return immediately after sending a terminal validation or authorisation response. Prefer a linear async handler whose success response occurs once after all required awaited work. Keep response writing at the request boundary instead of allowing deeply nested service functions to write to res.

Give timeout and completion one shared cancellation and settlement mechanism. Abort supported downstream operations when the deadline expires. A final headersSent check can be defensive, but it should not be the only protection against two independent response owners.

In Express-style error middleware, delegate when headers have already been sent so the framework can handle the incomplete response according to its contract. Before headers are sent, select one error response and return. Do not call next after sending that error body.

For streaming endpoints, distinguish a failure before the first byte from a failure after commitment. Validate predictable errors up front; after commitment, record the failure and close the stream cleanly where possible. Clients must recognise truncation rather than accept a partial file as success.

async function handler(req, res, next) {
  if (!req.body.name) {
    return res.status(400).json({ error: "name is required" });
  }
  try {
    const result = await createRecord(req.body);
    return res.status(201).json(result);
  } catch (error) {
    return next(error);
  }
}

function errorHandler(error, req, res, next) {
  if (res.headersSent) return next(error);
  return res.status(500).json({ error: "request failed" });
}

How to stop it coming back

• Keep domain services independent of the HTTP response object
• Test late completion after timeout and errors after a stream’s first chunk
• Require terminal response branches to end control flow explicitly
• Track response completion and downstream cancellation under the same request ID

FAQ

Related

Other errors engineers hit next to this one

• Event loop blocked by synchronous work
• pg client already connected or released twice
• Sequelize / Knex pool acquire timeout
• ERR_STREAM_PREMATURE_CLOSE during an upload
• Process exits before asynchronous writes finish
• ERR_MODULE_NOT_FOUND during ESM/CommonJS migration
• Unbounded JSON body blocks the loop or exhausts memory
• Undici / fetch connections remain occupied