nodejs/undici

Invalid HTTP2 headers should be recoverable

Open

#4356 opened on Jul 22, 2025

View on GitHub
 (6 comments) (0 reactions) (0 assignees)JavaScript (5,319 stars) (444 forks)batch import
buggood first issue

Description

Bug Description

If an invalid HTTP2 header is sent by the server, the client should be able to recover by retrying the operation. Right now it results in an uncaughtException. See https://github.com/nodejs/undici/discussions/4341 for more details.

Reproducible By

To reproduce, a mock reply will need to be constructed where an HTTP2 connection to a server gets a response with an HTTP1 header like "http2-settings".

Ideally a runtime error is thrown, which can be caught in a block where Undici can be directed to retry the operation with a new connection.

Logs & Screenshots

Here is an example stack trace from when this occurs:

{err":{"type":"TypeError","message":"HTTP/1 Connection specific headers are forbidden: \"http2-settings\"","stack":"TypeError: HTTP/1 Connection specific headers are forbidden: \"http2-settings\"\n    
at mapToHeaders (node:internal/http2/util:651:13)\n    
at ClientHttp2Session.request (node:internal/http2/core:1813:25)\n    
at writeH2 (/.../node_modules/undici/lib/dispatcher/client-h2.js:469:22)\n    
at Object.write (/.../node_modules/undici/lib/dispatcher/client-h2.js:119:14)\n    
at _resume (/.../node_modules/undici/lib/dispatcher/client.js:601:50)\n    
at resume (/.../node_modules/undici/lib/dispatcher/client.js:303:28\n    
at node:internal/process/task_queues:140:7\n    
at AsyncResource.runInAsyncScope (node:async_hooks:206:9)\n    
at AsyncResource.runMicrotask (node:internal/process/task_queues:137:8)","code":"ERR_HTTP2_INVALID_CONNECTION_HEADERS"}

Environment

This was encountered using Node.js 22 on RHEL9.

Additional context

Contributor guide

Tech stack
nodejsjavascript
Domain
backend
Issue type
bug
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
3
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
half day
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
active
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
clear
Prerequisites
Node.js HTTP/2undici codebase
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
50
Research direction
Examine the `writeH2` function in `lib/dispatcher/client h2.js` where the error is thrown. Understand how headers are mapped and why invalid HTTP/1 connection specific headers cause uncaught exceptions. Investigate how to catch the `ERR HTTP2 INVALID CONNECTION HEADERS` error and implement retry logic for the client. Refer to the discussion at https://github.com/nodejs/undici/discussions/4341 for additional context.