{"record":{"id":"3010737f4aae365c","repo":"JuliusBrussee/caveman","slug":"unsupported-version-301073","errorCode":"unsupported_version","errorMessage":"unsupported_version","messagePattern":"unsupported_version","errorType":"error_code","errorClass":"MiddlewareError","httpStatus":null,"severity":"error","filePath":"packages/sdk/python/caveman_cloud/middleware/validate.py","lineNumber":51,"sourceCode":"\ndef capabilities(value: Any) -> dict[str, Any]:\n    try:\n        if (type(value[\"schema_version\"]) is not int or value[\"schema_version\"] != 1 or not token(value[\"policy_revision\"])\n                or not isinstance(value[\"runtime_build\"], str) or value[\"mode\"] not in (\"record\", \"compress\")\n                or not isinstance(value[\"transforms\"], list) or len(value[\"transforms\"]) > 128\n                or not all(integer(value[\"limits\"][k]) and value[\"limits\"][k] > 0 for k in (\"deadline_ms\", \"request_bytes\", \"segment_bytes\", \"page_bytes\"))\n                or not integer(value[\"retention_seconds\"]) or type(value[\"recovery\"]) is not bool\n                or type(value[\"persistent\"]) is not bool):\n            raise ValueError()\n        seen = set()\n        for t in value[\"transforms\"]:\n            if (not token(t[\"transform_id\"]) or t[\"transform_id\"] in seen or not token(t[\"implementation_version\"])\n                    or not isinstance(t[\"eligible_segment_kinds\"], list) or t[\"recovery\"] not in (\"exact_ccr\", \"none\") or t[\"deterministic\"] is not True):\n                raise MiddlewareError(\"unknown_capability\")\n            seen.add(t[\"transform_id\"])\n        return value\n    except (KeyError, TypeError, ValueError) as error:\n        raise MiddlewareError(\"unsupported_version\") from None\n\n\ndef plan(value: Any, request: dict, input_digest: str, caps: dict) -> dict:\n    try:\n        p = value\n        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\n                or p[\"policy_revision\"] != request[\"policy\"][\"revision\"] or not digest(p[\"replacement_set_id\"])\n                or p[\"status\"] not in (\"optimized\", \"bypassed\", \"record\") or not token(p[\"reason\"])\n                or not isinstance(p[\"replacements\"], list) or not isinstance(p[\"skipped\"], list)):\n            raise ValueError()\n        m = p[\"measurement\"]\n        recovery = p[\"recovery\"]\n        if (m[\"basis\"] != \"inferred\" or m[\"scope\"] != \"segment\" or m[\"verified_saved_usd\"] != 0\n                or not isinstance(m[\"tokenizer\"], str)\n                or not all(integer(m[k]) for k in (\"tokens_before\", \"tokens_after\", \"unique_tokens_reduced\", \"recovery_overhead_tokens\"))\n                or m[\"tokens_after\"] > m[\"tokens_before\"] or p[\"stability\"][\"provider_bytes\"] != \"unobserved\"\n                or p[\"stability\"][\"provider_cache_hits\"] != \"unobserved\" or p[\"stability\"][\"native\"] not in (\"persistent_choices\", \"unavailable\")\n                or type(recovery[\"available\"]) is not bool or type(recovery[\"persistent\"]) is not bool or not integer(recovery[\"expires_at\"])):","sourceCodeStart":33,"sourceCodeEnd":69,"githubUrl":"https://github.com/JuliusBrussee/caveman/blob/3ee70a102609e550bd2e68004bf5990a9341c851/packages/sdk/python/caveman_cloud/middleware/validate.py#L33-L69","documentation":"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'.","triggerScenarios":"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.","commonSituations":"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).","solutions":["Align versions: use an SDK/middleware pair that both speak capability schema_version 1, or upgrade both","Fix the manifest so it has all required v1 fields with correct types (policy_revision token, persistent bool, transforms list)","Confirm you are passing the capabilities document, not a plan or page object","Pre-check schema_version == 1 and required keys before the call"],"exampleFix":"# before\ncaps_doc = {\"schema_version\": \"1\", ...}  # unsupported_version\n// after\ncaps_doc = {\"schema_version\": 1, \"policy_revision\": \"r7\", \"persistent\": True, \"transforms\": [...]}","handlingStrategy":"validation","validationCode":"def capabilities_doc_ok(doc) -> bool:\n    return (isinstance(doc, dict)\n            and type(doc.get(\"schema_version\")) is int\n            and doc[\"schema_version\"] == 1\n            and isinstance(doc.get(\"transforms\"), list)\n            and isinstance(doc.get(\"persistent\"), bool))\n# check before calling capabilities()","typeGuard":"def is_v1_capabilities_doc(doc) -> bool:\n    return isinstance(doc, dict) and doc.get(\"schema_version\") == 1","tryCatchPattern":"try:\n    caps = client.capabilities(doc)\nexcept MiddlewareError as e:\n    if e.args[0] == \"unsupported_version\":\n        log.error(\"manifest is not capability schema v1; check versions/keys\")\n    raise","preventionTips":["Pin SDK and middleware to compatible versions that share schema_version 1","Validate manifests against the v1 schema in CI before deployment","Ensure you pass the capabilities document, not a plan/page object","Check schema_version first whenever debugging manifest rejections"],"tags":["validation","schema","versioning","python"],"backgroundTag":"schema-validation-failed","analyzedSha":"3ee70a102609e550bd2e68004bf5990a9341c851","analyzedAt":"2026-09-20T15:53:39.229Z","contentChangedAt":"2026-09-20T15:53:39.229Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}