Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท HTTP, HTTPS, net, TLS, dgram and dns

Node.js res.writeHead() method

Reference for response.writeHead(): set the status code, an optional reason phrase and headers in one call, how it merges with setHeader(), and its errors.

res.writeHead(statusCode[, statusMessage][, headers]) sets the response status line and headers in one call and marks them ready to send. It is the compact alternative to assigning res.statusCode and calling res.setHeader() several times.

Call it at most once, before the body. Because it also fixes the headers, you cannot add or change any header afterwards. If you do not call it, Node sends the headers implicitly with the first write() or end(), using res.statusCode (200 by default) and the headers set with setHeader().

NODE
import http from "node:http";

http.createServer((req, res) => {
  res.writeHead(404, { "Content-Type": "text/plain" });
  res.end("Not found");
});

Try it

Node.js Status, reason phrase and headers

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Node.js Merging with setHeader and the errors

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Syntax

NODE
res.writeHead(statusCode: number, headers?: object | array): this
res.writeHead(statusCode: number, statusMessage: string, headers?: object | array): this
Name Description
statusCode An integer from 100 to 999.
statusMessage Reason phrase after the code. Default: the standard one (OK, Not Found).
headers An object ({ "Content-Type": "text/plain" }) or a flat array of alternating names and values. A value may be an array to send a header several times.

Returns: the response, so calls can be chained.

Errors and edge cases:

  • A status outside 100-999 throws ERR_HTTP_INVALID_STATUS_CODE.
  • Calling it again after the headers were sent throws ERR_HTTP_HEADERS_SENT.
  • Invalid header names or values throw ERR_INVALID_HTTP_TOKEN or ERR_INVALID_CHAR.
  • Headers passed to writeHead() take precedence over headers of the same name set earlier with setHeader().

Usage notes

  • writeHead() does not send bytes immediately; the headers go out with the first body chunk or end(). Use res.flushHeaders() to send them at once, for example before a long-running stream.
  • If you already called setHeader("Content-Length", ...), do not pass a different length here. Mismatched lengths corrupt the response.
  • Do not rely on a custom statusMessage for logic: HTTP/2 has no reason phrases and clients ignore them.
  • A thrown ERR_HTTP_INVALID_STATUS_CODE happens because the code is checked eagerly; fix the value rather than catching it.
  • Informational codes (1xx) are better sent with res.writeContinue() or res.writeEarlyHints(), which do not end the response head.
  • Prefer assigning res.statusCode and using setHeader() when headers are assembled in several places (middleware); use writeHead() for a simple one-shot response.