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().
import http from "node:http"; http.createServer((req, res) => { res.writeHead(404, { "Content-Type": "text/plain" }); res.end("Not found"); });
Try it
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.
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
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_TOKENorERR_INVALID_CHAR. - Headers passed to
writeHead()take precedence over headers of the same name set earlier withsetHeader().
Usage notes
writeHead()does not send bytes immediately; the headers go out with the first body chunk orend(). Useres.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
statusMessagefor logic: HTTP/2 has no reason phrases and clients ignore them. - A thrown
ERR_HTTP_INVALID_STATUS_CODEhappens because the code is checked eagerly; fix the value rather than catching it. - Informational codes (1xx) are better sent with
res.writeContinue()orres.writeEarlyHints(), which do not end the response head. - Prefer assigning
res.statusCodeand usingsetHeader()when headers are assembled in several places (middleware); usewriteHead()for a simple one-shot response.