JuliusBrussee/caveman · error · MiddlewareError

unsupported_version

unsupported_version

Error message

unsupported_version

What it means

MiddlewareError raised by capabilities() when the manifest fails structural/version checks that are NOT transform-specific: schema_version missing/not 1, missing or malformed fields raising KeyError/TypeError/ValueError. It is the catch-all for 'this manifest is not a v1 capability document I understand'.

Solutions

1. Align versions: use an SDK/middleware pair that both speak capability schema_version 1, or upgrade both
2. Fix the manifest so it has all required v1 fields with correct types (policy_revision token, persistent bool, transforms list)
3. Confirm you are passing the capabilities document, not a plan or page object
4. Pre-check schema_version == 1 and required keys before the call

Example fix

# before
caps_doc = {"schema_version": "1", ...}  # unsupported_version
// after
caps_doc = {"schema_version": 1, "policy_revision": "r7", "persistent": True, "transforms": [...]}

def capabilities_doc_ok(doc) -> bool:
    return (isinstance(doc, dict)
            and type(doc.get("schema_version")) is int
            and doc["schema_version"] == 1
            and isinstance(doc.get("transforms"), list)
            and isinstance(doc.get("persistent"), bool))
# check before calling capabilities()

def is_v1_capabilities_doc(doc) -> bool:
    return isinstance(doc, dict) and doc.get("schema_version") == 1

try:
    caps = client.capabilities(doc)
except MiddlewareError as e:
    if e.args[0] == "unsupported_version":
        log.error("manifest is not capability schema v1; check versions/keys")
    raise

When it happens

Trigger: Calling capabilities() with a dict whose schema_version is absent, a string like "1", or != 1; missing policy_revision, persistent flag, or transforms array; wrong nesting anywhere in the document.

Common situations: Middleware and SDK version skew (middleware emits schema_version 2, SDK expects 1); YAML/JSON hand-authored manifests missing required keys; passing the wrong object entirely (e.g., the plan instead of the capabilities doc).

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

• unknown_capability
• artifact_id is required
• ASGI context resolver or request bounds are invalid
• assemble requires model and session_id
• assembly slot id must be non-empty and unique

AI-assisted analysis of JuliusBrussee/caveman@3ee70a1026 (2026-09-20). Data as JSON: /api/errors/3010737f4aae365c. Report an issue: GitHub.

Appendix: source

Thrown at packages/sdk/python/caveman_cloud/middleware/validate.py:51

def capabilities(value: Any) -> dict[str, Any]:
    try:
        if (type(value["schema_version"]) is not int or value["schema_version"] != 1 or not token(value["policy_revision"])
                or not isinstance(value["runtime_build"], str) or value["mode"] not in ("record", "compress")
                or not isinstance(value["transforms"], list) or len(value["transforms"]) > 128
                or not all(integer(value["limits"][k]) and value["limits"][k] > 0 for k in ("deadline_ms", "request_bytes", "segment_bytes", "page_bytes"))
                or not integer(value["retention_seconds"]) or type(value["recovery"]) is not bool
                or type(value["persistent"]) is not bool):
            raise ValueError()
        seen = set()
        for t in value["transforms"]:
            if (not token(t["transform_id"]) or t["transform_id"] in seen or not token(t["implementation_version"])
                    or not isinstance(t["eligible_segment_kinds"], list) or t["recovery"] not in ("exact_ccr", "none") or t["deterministic"] is not True):
                raise MiddlewareError("unknown_capability")
            seen.add(t["transform_id"])
        return value
    except (KeyError, TypeError, ValueError) as error:
        raise MiddlewareError("unsupported_version") from None


def plan(value: Any, request: dict, input_digest: str, caps: dict) -> dict:
    try:
        p = value
        if (type(p["schema_version"]) is not int or p["schema_version"] != 1 or p["request_id"] != request["request_id"] or p["input_digest"] != input_digest
                or p["policy_revision"] != request["policy"]["revision"] or not digest(p["replacement_set_id"])
                or p["status"] not in ("optimized", "bypassed", "record") or not token(p["reason"])
                or not isinstance(p["replacements"], list) or not isinstance(p["skipped"], list)):
            raise ValueError()
        m = p["measurement"]
        recovery = p["recovery"]
        if (m["basis"] != "inferred" or m["scope"] != "segment" or m["verified_saved_usd"] != 0
                or not isinstance(m["tokenizer"], str)
                or not all(integer(m[k]) for k in ("tokens_before", "tokens_after", "unique_tokens_reduced", "recovery_overhead_tokens"))
                or m["tokens_after"] > m["tokens_before"] or p["stability"]["provider_bytes"] != "unobserved"
                or p["stability"]["provider_cache_hits"] != "unobserved" or p["stability"]["native"] not in ("persistent_choices", "unavailable")
                or type(recovery["available"]) is not bool or type(recovery["persistent"]) is not bool or not integer(recovery["expires_at"])):

View on GitHub (pinned to 3ee70a1026)