OutgoingHttpHeaders `location` is officially allowed to be undefined but can't be undefined

[ericmorand]

Version

Confirmed from Node.js 20 to 23

Platform

Linux janet 6.14.0-34-generic #34-Ubuntu SMP PREEMPT_DYNAMIC Wed Sep 17 09:21:29 UTC 2025 x86_64 x86_64 x86_64 GNU/Linux

Subsystem

http

What steps will reproduce the bug?

Set the location header of a Server Response to undefined, and end the response.

How often does it reproduce? Is there a required condition?

This happens every single time.

What is the expected behavior? Why is that the expected behavior?

Since it is officially accepted that the location header can be undefined, it should accept to be undefined.

For information, this is the official type definition for this header:

        location?: string | undefined;

What do you see instead?

TypeError [ERR_HTTP_INVALID_HEADER_VALUE]: Invalid value "undefined" for header "location"
    at ServerResponse.setHeader (node:_http_outgoing:702:3)

Additional information

({}).location === ({location: undefined}).location;

https://tc39.es/ecma262/#sec-ordinaryget

is true: both operands are strictly equal to undefined. I'm not sure at all if this is related to that, but it seems really unexpected that the absence of the location header is a valid situation (even though the value of the location header in this situation is undefined), and that the presence of the location header with a value set to undefined is not a valid situation.

[Renegade334]

It sounds like what you're referring to is a @types/node issue rather than a Node.js issue. The docs do state, albeit obliquely, that setting a header value to undefined will throw (this validation is performed for each key-value pair in the headers object, hence why the property being absent and the property being set to undefined are observably different)

[Renegade334]

Noted at DefinitelyTyped/DefinitelyTyped#73983.

[abdulfarid-dev]

working on a fix for this issue(#60418), will open a PR shortly

[Renegade334]

Will close this as intended behaviour. Any further discussion about the @types/node definitions can come under the linked DT issue.