Skip to content
Tutorials Center
My learning

Topics

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.