What causes "Too many headers (limit {_MAX_HEADER_COUNT})" in microsoft/aspire?

Ensure reads are not desynchronized: never read raw from the socket outside the framing helpers.

microsoft/aspire · error · ConnectionError

Too many headers (limit )

Error message

Too many headers (limit {_MAX_HEADER_COUNT})

What it means

Raised by _read_headers in the generated Python client when a response contains more HTTP-style headers than the client's maximum (_MAX_HEADER_COUNT). The client enforces a hard cap to protect against malformed or malicious peer responses and raises ConnectionError with the limit in the message.

Solutions

Ensure reads are not desynchronized: never read raw from the socket outside the framing helpers.
After any ConnectionError, discard the connection and reconnect rather than continuing on the same stream.
Check whether the host is behind a proxy or wrapper adding headers; strip or bypass it.
If the host legitimately needs more headers, update the generated module so client/server protocol limits match.

Example fix

// before
# continued reading on a connection after a prior timeout
data = client.invoke(...)

// after
# on any framing error, discard and reconnect
try:
    data = client.invoke(...)
except ConnectionError:
    client.reconnect()
    data = client.invoke(...)

Defensive patterns

Strategy: try-catch

Try / catch

try:
    data = client.invoke(...)
except ConnectionError as e:
    if "Too many headers" in str(e):
        client.reconnect()
        data = client.invoke(...)
    else:
        raise

Prevention

Never read raw bytes outside the framing helpers.
Always reconnect rather than continue after framing errors.
Keep client and generated module versions in sync with the host protocol.

When it happens

Trigger: A host (or whatever is on the other end of the pipe) emits a response with an excessive number of headers; framing corruption causing ordinary body bytes to be parsed as headers; proxying through something that injects many headers.

Common situations: Desynchronized framing after a previous partial read, so arbitrary bytes are interpreted as header lines; an intermediate tool adding debug headers; a protocol mismatch between client and server versions where the server includes far more metadata headers.

Understand the failure class

Background: payload too large / request exceeds maximum size: why libraries cap bytes and how to fix oversize payloads — this error's family across 50 libraries.

Related errors

AI-assisted analysis of microsoft/aspire@25830f84bd (2026-09-16). Data as JSON: /api/errors/a7beac768b5ca889. Report an issue: GitHub.

Appendix: source

Thrown at src/Aspire.Hosting.CodeGeneration.Python/PythonModuleBuilder.cs:936

                    if line.endswith(b"\r\n"):
                        return line[:-2]  # Remove \r\n

            def _read_headers(self) -> dict[str, str]:
                '''Read HTTP-style headers until empty line.

                Enforces limits on header count and total size to prevent
                memory exhaustion from a malicious peer.
                '''
                headers: dict[str, str] = {}
                total_bytes = 0
                while True:
                    line = self._read_line()
                    if not line:  # Empty line signals end of headers
                        break

                    total_bytes += len(line) + 2  # account for \r\n
                    if len(headers) >= _MAX_HEADER_COUNT:
                        raise ConnectionError(f"Too many headers (limit {_MAX_HEADER_COUNT})")
                    if total_bytes > _MAX_HEADER_BYTES:
                        raise ConnectionError(f"Headers too large (limit {_MAX_HEADER_BYTES} bytes)")

                    # Parse "Header-Name: value"
                    if b":" in line:
                        name, value = line.split(b":", 1)
                        headers[name.decode("utf-8").strip().lower()] = value.decode("utf-8").strip()
                return headers

            def _receive_loop(self) -> None:
                '''Receive and process messages from the server'''
                try:
                    while self._connected and self._socket:
                        # Read HTTP-style headers (HeaderDelimitedMessageHandler format)
                        headers = self._read_headers()
                        content_length = int(headers.get("content-length", "0"))

                        if content_length == 0:

View on GitHub (pinned to 25830f84bd)