Hmbown/CodeWhale · error · RuntimeError

Codewhale stream-json schema did not match v0.9.1

Error message

Codewhale stream-json schema did not match v0.9.1

What it means

Every stream-json event must declare schema 'codewhale.exec-stream' and schema_version 1 (the v0.9.1 contract). This RuntimeError means an event object had a missing or different schema/schema_version. The harness throws it to refuse output from incompatible Codewhale versions, since field semantics may have changed.

Solutions

1. Run the binary with --version and confirm it is exactly the version CodewhaleHarnessConfig.version pins
2. Remove/align binary_path overrides so the installed 0.9.1 release is used
3. Check whether the stream schema was bumped upstream and bump STREAM_SCHEMA_VERSION/harness together
4. Inspect the offending event to see which envelope field is missing or renamed
5. If a proxy rewrites events, forward the schema/schema_version fields verbatim

Example fix

# before
config = CodewhaleHarnessConfig(version="0.9.1", binary_path="/usr/local/bin/codewhale-new")
# after
config = CodewhaleHarnessConfig(version="0.9.1")  # let setup install pinned 0.9.1

def envelope_ok(event: dict) -> bool:
    return (event.get("schema") == "codewhale.exec-stream"
            and event.get("schema_version") == 1)

def has_valid_schema(event: object) -> bool:
    return (isinstance(event, dict)
            and event.get("schema") == "codewhale.exec-stream"
            and event.get("schema_version") == 1)

try:
    result = await harness.launch(ctx, trace, runtime, endpoint, secret, mcp_urls)
except RuntimeError as e:
    if "schema did not match" in str(e):
        logger.error("binary/schema version mismatch; re-pin Codewhale 0.9.1")
    raise

When it happens

Trigger: _parse_stream_receipt read an event dict where event['schema'] != STREAM_SCHEMA or event['schema_version'] != STREAM_SCHEMA_VERSION — i.e. the binary emits a different stream dialect than the pinned 0.9.1 one.

Common situations: binary_path pointing at a newer/older Codewhale than the pinned 0.9.1; a fork that renamed the schema; a relay that forwards events but drops or rewrites envelope fields.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• Item schema v is newer than supported v
• Thread schema v is newer than supported v
• Turn schema v is newer than supported v
• Automation run schema v
• Automation schema v is newer than supported v

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

Appendix: source

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

    terminal: dict[str, Any] | None = None
    ordered_types: list[str] = []
    for line_number, line in enumerate(stdout.splitlines(), start=1):
        if not line.strip():
            continue
        try:
            event = json.loads(line)
        except json.JSONDecodeError as error:
            raise RuntimeError(
                f"Codewhale stream-json line {line_number} was not valid JSON"
            ) from error
        if not isinstance(event, dict):
            raise RuntimeError(
                f"Codewhale stream-json line {line_number} was not an object"
            )
        if event.get("schema") != STREAM_SCHEMA or event.get(
            "schema_version"
        ) != STREAM_SCHEMA_VERSION:
            raise RuntimeError("Codewhale stream-json schema did not match v0.9.1")
        event_type = event.get("type")
        if event_type not in _EVENT_TYPES:
            raise RuntimeError("Codewhale stream-json contained an unknown event type")
        counts[event_type] += 1
        ordered_types.append(event_type)
        if event_type == "metadata":
            if terminal is not None:
                raise RuntimeError("Codewhale emitted more than one terminal metadata receipt")
            meta = event.get("meta")
            if not isinstance(meta, dict) or meta.get("receipt_kind") != "terminal":
                raise RuntimeError("Codewhale metadata event was not a terminal receipt")
            terminal = _bounded_terminal(meta)

    if terminal is None:
        raise RuntimeError("Codewhale stream-json omitted terminal metadata")
    if counts["done"] != 1 or not ordered_types or ordered_types[-1] != "done":
        raise RuntimeError("Codewhale stream-json did not end with exactly one done event")
    if ordered_types[-2:-1] != ["metadata"]:

View on GitHub (pinned to 433685b202)