microsoft/aspire · error · ConnectionError

Headers too large (limit bytes)

Error message

Headers too large (limit {_MAX_HEADER_BYTES} bytes)

What it means

The generated Python client reads HTTP-style headers from the AppHost socket connection and enforces a cumulative size budget of _MAX_HEADER_BYTES (8 KB) across all header lines (counting the trailing CRLF). If the accumulated header bytes exceed that limit before the blank terminator line, it raises ConnectionError to protect against malformed or malicious framing from the peer. This is a framing-safety guard, not a normal operational error.

Solutions

1. Verify you are connecting to the correct AppHost endpoint (right port/process, not a proxy).
2. Check that the AppHost CLI/CLI-generated module and server versions match; rebuild the Python module against the running AppHost version.
3. Reset the connection (recreate the client) in case the stream is desynchronized from a prior failed read.
4. If legitimate headers are genuinely large, report/upgrade since the 8 KB limit is fixed in the generated module.

Example fix

// before
client = AspireClient(host, port)  # wrong port: hit a dev proxy injecting headers
// after
client = AspireClient("127.0.0.1", apphost_port)  # port from AppHost output, direct connection

def check_headers_safe():
    return client.is_connected() if hasattr(client, 'is_connected') else True

try:
    result = client.ping()
except ConnectionError as e:
    if 'Headers too large' in str(e):
        client = recreate_client()  # resync/reconnect
    else:
        raise

When it happens

Trigger: Calling any client method (ping, authenticate, invoke_capability) when the AppHost server's response header block exceeds 8 KB total, or when a corrupted/hostile peer streams header lines without a blank-line terminator.

Common situations: A proxy or intermediate device injecting large headers; connecting to the wrong process/port that speaks a different protocol; a version mismatch where the AppHost emits unexpectedly large header sets; a desynchronized socket stream misinterpreting body bytes as 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

• Message too large: bytes (limit bytes)
• Too many headers (limit )
• Connection closed
• Not connected to AppHost
• Pipe not found

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

Appendix: source

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

            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:
                            continue

View on GitHub (pinned to 25830f84bd)