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 event must carry schema == "codewhale.exec-stream" and schema_version == 1 (STREAM_SCHEMA_VERSION). This error means a parsed event object is missing those keys or carries different values, so the harness rejects the whole stream as not conforming to the v0.9.1 contract it is built against.

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

Solutions

1. Check the first parsed event in stdout: it must contain "schema": "codewhale.exec-stream" and "schema_version": 1.
2. Use the harness-pinned Codewhale release (version='0.9.1') instead of an untested binary_path build.
3. If you control the facade, stamp every emitted line with the exact schema and schema_version constants the harness expects.
4. If you intentionally upgraded the stream schema, update STREAM_SCHEMA/STREAM_SCHEMA_VERSION in harness.py in the same change and re-run the harness tests.

Example fix

# before: event lacks the envelope
{"type": "content", "text": "hi"}

# after: event carries the v0.9.1 envelope
{"schema": "codewhale.exec-stream", "schema_version": 1, "type": "content", "text": "hi"}

def events_match_schema(stdout: str) -> bool:
    for line in stdout.splitlines():
        if not line.strip():
            continue
        event = json.loads(line)
        if not isinstance(event, dict):
            return False
        if event.get("schema") != "codewhale.exec-stream" or event.get("schema_version") != 1:
            return False
    return True

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

When it happens

Trigger: Running a Codewhale binary whose stream schema name or version differs from the harness constants: a newer release that bumped schema_version, a facade that omits the schema envelope, or a hand-rolled emitter that only sends type/payload without the schema fields.

Common situations: Version skew between the harness (pinned to release 0.9.1 via CodewhaleHarnessConfig.version) and a binary_path override pointing at a locally built or newer/older facade; third-party tools that mimic the event format but not the envelope; forgetting the envelope in a custom stub used for local candidate testing.

Related errors

• Codewhale stream-json contained an unknown event type
• Codewhale stream-json line {line_number} was not an object
• Codewhale emitted more than one terminal metadata receipt
• Codewhale metadata event was not a terminal receipt
• Codewhale stream-json did not end with exactly one done even

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