microsoft/aspire · error · ConnectionError

Message too large: bytes (limit bytes)

Error message

Message too large: {content_length} bytes (limit {_MAX_MESSAGE_SIZE} bytes)

What it means

After parsing response headers, the client reads content-length and rejects messages larger than _MAX_MESSAGE_SIZE (64 MB) with a ConnectionError before attempting to read the body. This prevents unbounded memory allocation from a malformed or hostile response. It indicates protocol corruption or a peer sending data that violates the AppHost wire contract.

Solutions

1. Confirm the endpoint is the actual AppHost socket, not a proxy or unrelated HTTP server.
2. Recreate the client connection to resynchronize the socket stream.
3. Match client module and AppHost versions (regenerate/rebuild the Python module).
4. If a legitimate payload exceeds 64 MB, reduce the request size (e.g., smaller capability arguments) or report the scenario.

Example fix

// before
result = client.invoke_capability("export", {"data": huge_blob})  # >64MB args
// after
result = client.invoke_capability("export", {"data": chunk})  # send in chunks <64MB

import sys
def payload_within_limit(args):
    return sys.getsizeof(repr(args)) < 64 * 1024 * 1024

try:
    result = client.invoke_capability(cap, args)
except ConnectionError as e:
    if 'Message too large' in str(e):
        raise ValueError('Capability payload exceeds 64MB wire limit') from e
    raise

When it happens

Trigger: Any request/response exchange where the server (or whatever is on the socket) advertises a content-length greater than 64 MB.

Common situations: Connecting to the wrong service that streams large bodies; a desynchronized stream misreading body bytes as a header content-length; an AppHost/server version mismatch producing oversized frames; proxy interference mangling the framing.

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

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

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

Appendix: source

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

                    # 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

                        if content_length > _MAX_MESSAGE_SIZE:
                            raise ConnectionError(
                                f"Message too large: {content_length} bytes "
                                f"(limit {_MAX_MESSAGE_SIZE} bytes)"
                            )

                        # Read message content
                        message_bytes = self._recv_exactly(content_length)
                        message_str = message_bytes.decode("utf-8")
                        message = json.loads(message_str)
                        if self.debug:
                            if message.get("result") == "pong":
                                _logger.debug("<- %s", message)
                            else:
                                _logger.info("<- %s", message)

                        # Handle response or request
                        if "method" in message:
                            # This is a request from the server (callback invocation)
                            self._handle_server_request(message)

View on GitHub (pinned to 25830f84bd)