Hmbown/CodeWhale · error · RuntimeError

Codewhale terminal receipt exceeded its string bound

Error message

Codewhale terminal receipt exceeded its string bound

What it means

Terminal receipt string fields (model, sha256 digests, posture names, etc.) are capped at MAX_TERMINAL_STRING_CHARS = 512. This RuntimeError means a string field in the metadata event's 'meta' exceeded that bound. The harness throws it to keep trace metadata bounded — an oversized string indicates a malformed or hostile receipt, so it refuses to store it.

Solutions

1. Dump the raw metadata event from the program stdout to find which field is oversized
2. Ensure the configured binary is the genuine pinned Codewhale release, not a wrapper or shim
3. Check for environment variables or config that could bloat model/route identifiers
4. If a legitimate long field is expected, raise MAX_TERMINAL_STRING_CHARS in the harness and re-verify
5. Compare binary_sha256/config_sha256 output against expected values to detect tampering

Example fix

null

MAX = 512
oversized = [k for k, v in meta.items()
             if isinstance(v, str) and len(v) > MAX]
assert not oversized, f"oversized receipt fields: {oversized}"

def bounded(value: object) -> bool:
    return not isinstance(value, str) or len(value) <= 512

try:
    receipt = await harness.launch(ctx, trace, runtime, endpoint, secret, mcp_urls)
except RuntimeError as e:
    if "exceeded its string bound" in str(e):
        logger.error("receipt string bound violated; check binary integrity")
    raise

When it happens

Trigger: _bounded_terminal, called while parsing the 'metadata' event in the stream-json output, found a string field from _TERMINAL_FIELDS longer than 512 characters — e.g. a giant model identifier, padded hash, or embedded payload.

Common situations: Wrapping a proxy/wrapper binary that injects extra data into receipt fields; a fork or patched Codewhale writing verbose field values; JSON with multiline or corrupted output mistaken for metadata.

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

• append_allow_rules only accepts action = "allow"
• Codewhale credentials directory has an unsupported component
• Codewhale terminal receipt contained an invalid count
• Codewhale terminal receipt exceeded its total bound
• CodewhalePet/1

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

Appendix: source

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

def _has_version(output: str, version: str) -> bool:
    return (
        re.search(
            rf"(?<![0-9A-Za-z.+-]){re.escape(version)}(?![0-9A-Za-z.+-])",
            output,
        )
        is not None
    )


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

View on GitHub (pinned to 433685b202)