Skip to content

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

Node.js res.setHeader() method

Reference for response.setHeader() and its companions getHeader(), hasHeader(), removeHeader() and appendHeader(): multiple values, Set-Cookie arrays and errors.

res.setHeader(name, value) sets a single response header. It can be called several times, from different places in your code, until the headers are sent. Setting a header that already exists replaces it.

Header names are case-insensitive, and Node remembers them in lower case for the getters. A value is a string, a number, or an array of strings, which sends the header several times. That is how you send more than one Set-Cookie. The headers go out when the first part of the body is written, or with writeHead().

NODE
import http from "node:http";

http.createServer((req, res) => {
  res.setHeader("Content-Type", "text/html; charset=utf-8");
  res.setHeader("Set-Cookie", ["a=1; HttpOnly", "b=2; Secure"]);
  res.end("<p>hi</p>");
});

Try it

Node.js Setting, reading, appending and removing

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 Invalid headers and late changes

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.setHeader(name: string, value: string | number | readonly string[]): this
res.getHeader(name: string): string | number | string[] | undefined
res.getHeaders(): object            // null-prototype object, lower-case names
res.getHeaderNames(): string[]
res.hasHeader(name: string): boolean
res.removeHeader(name: string): void
res.appendHeader(name: string, value: string | readonly string[]): this
Name Description
name Header name. Must be a valid HTTP token: letters, digits and characters such as - and _, no spaces.
value A string, a number, or an array of strings for repeated headers.

Returns: setHeader() and appendHeader() return the response so calls can be chained. Getters return what was stored, with names in lower case.

Errors and edge cases:

  • Setting a header after the headers were sent throws ERR_HTTP_HEADERS_SENT.
  • An invalid name throws ERR_INVALID_HTTP_TOKEN.
  • A value containing a line break or other forbidden character throws ERR_INVALID_CHAR, which blocks header-injection attacks.
  • A value of undefined throws ERR_HTTP_INVALID_HEADER_VALUE.
  • getHeader() returns the stored form: a number stays a number, an array stays an array.

Usage notes

  • Use an array for several Set-Cookie headers. Joining cookies with commas is wrong, because cookie dates contain commas.
  • setHeader() replaces; appendHeader() (added in Node.js 18.3) adds a further value for the same name.
  • res.writeHead() headers override setHeader() ones with the same name; res.getHeaders() shows only the headers set through setHeader() until writeHead() merges them.
  • Set Content-Type with a charset for text (text/plain; charset=utf-8), and Cache-Control explicitly for anything cacheable.
  • Header names are case-insensitive, but Node sends them as you wrote them for HTTP/1.1. HTTP/2 lower-cases everything, so never depend on casing.
  • Check res.headersSent before attempting to change headers in error handlers.
  • Do not copy untrusted input into a header name, and be careful with values such as Location, which can enable open redirects.