Hmbown/CodeWhale · error · RuntimeError

Codewhale terminal receipt exceeded its string bound

Error message

Codewhale terminal receipt exceeded its string bound

What it means

_bounded_terminal enforces MAX_TERMINAL_STRING_CHARS=512 on every string field of the terminal metadata (model, provider_id, route_source, the sha256 fields, error_category, ...) while parsing stdout. Longer strings raise RuntimeError and fail an otherwise successful run; the bound keeps trace metadata small and deterministic.

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 8880682c63)

Solutions

Truncate terminal metadata strings to at most 512 characters in the emitter
Move long diagnostics into non-metadata events; the harness retains only scalar summaries
Keep the facade's terminal vocabulary aligned with the pinned release's field set

Example fix

# before
meta = {'error_category': long_stack_trace}
# after
meta = {'error_category': long_stack_trace[:512]}

Defensive patterns

Strategy: validation

Validate before calling

MAX = 512
meta = {k: (v[:MAX] if isinstance(v, str) else v) for k, v in meta.items()}

Prevention

Cap every string written to terminal metadata at 512 chars
Keep diagnostics in event payloads, not receipt fields
Diff facade receipts against the terminal-field expectations in tests

When it happens

Trigger: A facade embedding a stack trace or long message in error_category; binary versions adding unbounded string fields to the terminal receipt; identifiers carrying long generated suffixes.

Common situations: Debug builds stuffing diagnostics into receipt fields; facade authors copying whole outputs into metadata; schema drift adding descriptive fields.

Related errors

AI-assisted analysis of Hmbown/CodeWhale@8880682c63 (2026-08-16). Data as JSON: /api/errors/d9e7404615c5ab6c. Report an issue: GitHub.