Hmbown/CodeWhale · error · RuntimeError

Codewhale terminal receipt exceeded its total bound

Error message

Codewhale terminal receipt exceeded its total bound

What it means

After per-field checks, the canonicalized terminal receipt is JSON-encoded and must be at most MAX_TERMINAL_RECEIPT_BYTES = 8192 bytes. This RuntimeError means the receipt as a whole exceeded that budget even though individual fields passed. The harness throws it because it stores the receipt in trace.info and refuses unbounded metadata.

Solutions

1. Dump the encoded receipt length per field to find what dominates the 8KB budget
2. Use the official pinned binary rather than a wrapper that adds fields
3. If the schema legitimately grew, raise MAX_TERMINAL_RECEIPT_BYTES in the harness deliberately
4. Trim receipt content at the source (shorter identifiers, fewer optional fields set)
5. Verify STREAM_SCHEMA_VERSION handling matches the emitting binary's schema

Example fix

# before
MAX_TERMINAL_RECEIPT_BYTES = 8_192
# after (only if the receipt schema legitimately grew)
MAX_TERMINAL_RECEIPT_BYTES = 16_384

import json
encoded = json.dumps(meta, sort_keys=True, separators=(",", ":")).encode()
assert len(encoded) <= 8192, f"receipt too large: {len(encoded)} bytes"

try:
    receipt = await harness.launch(ctx, trace, runtime, endpoint, secret, mcp_urls)
except RuntimeError as e:
    if "exceeded its total bound" in str(e):
        logger.error("terminal receipt >8KB; audit emitter fields")
    raise

When it happens

Trigger: _bounded_terminal finished collecting all _TERMINAL_FIELDS from the metadata event but json.dumps(terminal, sort_keys=True, separators=(',',':')) serialized to more than 8192 bytes.

Common situations: A wrapped/patched binary stuffing many or very long (but individually <=512 char) fields; a future schema adding fields beyond the byte budget; debugging builds emitting verbose identifiers across all sha256/config fields.

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

• Codewhale terminal receipt contained an invalid count
• Codewhale terminal receipt exceeded its string bound
• Invalid evidence bundle or record limit exceeded.
• Invalid pet random stream.
• Invalid pet score checkpoint.

AI-assisted analysis of Hmbown/CodeWhale@433685b202 (2026-09-15). Data as JSON: /api/errors/0ddb1776e80eb736. Report an issue: GitHub.

Appendix: source

Thrown at integrations/verifiers-codewhale/codewhale_harness/harness.py:272

def _bounded_terminal(meta: dict[str, Any]) -> dict[str, Any]:
    terminal: dict[str, Any] = {}
    for key in _TERMINAL_FIELDS:
        if key not in meta or meta[key] is None:
            continue
        value = meta[key]
        if isinstance(value, str):
            if len(value) > MAX_TERMINAL_STRING_CHARS:
                raise RuntimeError("Codewhale terminal receipt exceeded its string bound")
        elif isinstance(value, int) and not isinstance(value, bool):
            if value < 0 or value > 2**63 - 1:
                raise RuntimeError("Codewhale terminal receipt contained an invalid count")
        else:
            raise RuntimeError("Codewhale terminal receipt contained a non-scalar field")
        terminal[key] = value
    encoded = json.dumps(terminal, sort_keys=True, separators=(",", ":")).encode()
    if len(encoded) > MAX_TERMINAL_RECEIPT_BYTES:
        raise RuntimeError("Codewhale terminal receipt exceeded its total bound")
    return terminal


def _install_script(version: str) -> str:
    version_q = shlex.quote(version)
    install_q = shlex.quote(INSTALL_DIR)
    release_q = shlex.quote(RELEASE_ROOT)
    return f"""
set -eu
version={version_q}
install_dir={install_q}
release_root={release_q}
if [ "$(uname -s)" != Linux ]; then
    echo "automatic Codewhale installation supports Linux runtimes; set binary_path" >&2
    exit 1
fi
case "$(uname -m)" in
    x86_64|amd64) platform=linux-x64 ;;

View on GitHub (pinned to 433685b202)