Flash5/flash/docs/http2/TROUBLESHOOTING.md

HTTP/2 troubleshooting

Confirm which protocol was selected

For TLS, the client and server must both offer h2 through ALPN. Enable FlashConfiguration.http2Enabled, use a certificate valid for the requested hostname, then check with curl --http2 -v https://host/path or nghttp -nv https://host/path. The trace must report ALPN h2; a successful HTTP/1.1 response usually means HTTP/2 was not enabled or the client did not offer it.

For plaintext, enable http2CleartextEnabled and use prior knowledge:

curl --http2-prior-knowledge -v http://host:port/path
nghttp -nv http://host:port/path

Flash does not support Upgrade: h2c. A client configured for Upgrade rather than prior knowledge will remain on HTTP/1.1.

Read GOAWAY and RST_STREAM

GOAWAY terminates or drains a connection; last_stream_id identifies the highest client stream the server may have processed. A client may retry a stream above that id only when its own request semantics make retry safe. RST_STREAM affects one stream and leaves the connection usable.

Error	What it usually means	What to check
NO_ERROR	Graceful shutdown or connection rotation.	Server lifecycle and configured connection lifetime.
PROTOCOL_ERROR	Invalid preface, pseudo-header ordering, stream state or frame semantics.	A verbose frame trace and the first rejected stream.
INTERNAL_ERROR	Handler, response production or I/O failed unexpectedly.	The server exception immediately preceding stream cancellation.
FLOW_CONTROL_ERROR	A window overflow or DATA exceeded available credit.	Client flow-control implementation and SETTINGS deltas.
SETTINGS_TIMEOUT	The peer did not complete required SETTINGS progress.	Network stalls or a non-compliant peer.
STREAM_CLOSED	A frame targeted a stream whose remote side or whole lifecycle was closed.	Late DATA/HEADERS and duplicate terminal frames.
FRAME_SIZE_ERROR	A frame length violated its type or the negotiated maximum.	The nine-byte frame header and peer frame-size configuration.
REFUSED_STREAM	Live or pending-output capacity was temporarily exhausted.	Client concurrency versus the advertised maximum; retry only when safe.
CANCEL	The request, handler or streamed response was cancelled.	Client cancellation and application producer logs.
COMPRESSION_ERROR	HPACK integer, Huffman, index or table update was invalid.	Header-block bytes and whether an intermediary rewrote them.
CONNECT_ERROR	A CONNECT tunnel failed.	Upstream tunnel or extended-CONNECT negotiation.
ENHANCE_YOUR_CALM	A configured abuse, rate, header, body or queue bound was exceeded.	Security controls and traffic rate before increasing a limit.
INADEQUATE_SECURITY	TLS does not meet HTTP/2 requirements.	TLS version, cipher suite and ALPN configuration.
HTTP_1_1_REQUIRED	The peer should retry using HTTP/1.1.	Protocol policy and intermediary compatibility.

Flash caps GOAWAY debug data, and clients must not depend on it being present. The numeric error code and last stream id are the reliable diagnostic fields.

Capture a frame trace

Flash does not log every frame in production: frame logs leak header and traffic metadata and add work to the hottest connection loop. Reproduce against a verbose client instead:

nghttp -nv https://host/path
curl --http2 -v https://host/path

nghttp -nv prints SETTINGS, HEADERS, DATA, WINDOW_UPDATE, RST_STREAM and GOAWAY in wire order. For a server-side-only failure, capture the connection with an approved packet tool; TLS traffic must be decrypted in a controlled environment. Never attach production header blocks or payloads to a ticket without redacting credentials and personal data.

Common misconfiguration patterns

1. HTTP/2 switch disabled. http2Enabled controls TLS ALPN and http2CleartextEnabled controls prior knowledge independently.
2. Wrong cleartext mode. The client sends Upgrade: h2c; Flash expects the RFC 9113 prior- knowledge preface on the shared plaintext listener.
3. ALPN or certificate mismatch. A custom TlsConfig.ofContext omits h2, or hostname verification rejects the certificate before HTTP/2 starts. Inspect the TLS handshake first.

If a connection closes under load rather than at startup, compare the observed rate and retained stream count with the security defaults, especially reset/stream creation budgets, the 64 concurrent-stream setting, header assembly time and stream idle time.