Hmbown/CodeWhale · error · RuntimeError

Codewhale metadata event was not a terminal receipt

Error message

Codewhale metadata event was not a terminal receipt

What it means

When `_parse_stream_receipt` encounters a `metadata` event, it requires `event["meta"]` to be a dict with `meta["receipt_kind"] == "terminal"`. This error means a metadata event was present but its shape or kind was wrong — missing `meta`, non-dict `meta`, or a different receipt kind — so no valid terminal receipt could be captured.

Solutions

1. Print the offending metadata event and compare its keys against the expected schema (`meta` dict with `receipt_kind == "terminal"`)
2. Rebuild/pin the Codewhale binary to the schema version matching STREAM_SCHEMA_VERSION in the harness
3. If intermediate receipts are legitimate, ensure they use a non-terminal `receipt_kind` and that exactly one terminal receipt exists
4. Fix mock/test fixtures to emit `meta` as an object with `receipt_kind: "terminal"`

Example fix

// before
{"type":"metadata","meta":{"kind":"terminal"}}
// after
{"type":"metadata","meta":{"receipt_kind":"terminal"}}

for e in events:
    if e.get("type") == "metadata":
        meta = e.get("meta")
        assert isinstance(meta, dict) and meta.get("receipt_kind") == "terminal", f"bad metadata: {e!r}"

def has_terminal_meta(event: dict) -> bool:
    meta = event.get("meta")
    return isinstance(meta, dict) and isinstance(meta.get("receipt_kind"), str) and meta["receipt_kind"] == "terminal"

try:
    receipt = _parse_stream_receipt(events)
except RuntimeError as e:
    if "not a terminal receipt" in str(e):
        log.error("metadata schema mismatch; compare binary version to harness STREAM_SCHEMA_VERSION")
    raise

When it happens

Trigger: A metadata event in the stream-json lacks the `meta` key, has `meta` set to a non-dict (string/list/null), or carries `receipt_kind` with any value other than `"terminal"` while `_parse_stream_receipt` (called from `launch()`) processes it at harness.py:376.

Common situations: Binary version mismatch where the agent emits a different receipt schema (e.g. `kind` instead of `receipt_kind`, or a progress/intermediate receipt); a truncated or hand-edited stream line; a mock stream written against an older schema.

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

• Codewhale emitted more than one terminal metadata receipt
• Codewhale stream-json did not end with exactly one done…
• Codewhale stream-json omitted terminal metadata
• Codewhale terminal metadata did not immediately precede done
• Codewhale terminal receipt omitted a valid

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

Appendix: source

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

        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"]:
        raise RuntimeError("Codewhale terminal metadata did not immediately precede done")
    for field in ["binary_sha256", "prompt_sha256"]:
        if not isinstance(terminal.get(field), str) or not _SHA256.fullmatch(
            terminal[field]
        ):
            raise RuntimeError(f"Codewhale terminal receipt omitted a valid {field}")
    return {
        "schema": STREAM_SCHEMA,
        "schema_version": STREAM_SCHEMA_VERSION,
        "events": dict(sorted(counts.items())),
        "terminal": terminal,

View on GitHub (pinned to 433685b202)