{"record":{"id":"1586b25afe5d6876","repo":"Comfy-Org/ComfyUI","slug":"layers-document-version-version-r-is-not-support","errorCode":null,"errorMessage":"LAYERS document version {version!r} is not supported","messagePattern":"LAYERS document version (.+?) is not supported","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"comfy_extras/nodes_compositor.py","lineNumber":32,"sourceCode":"    placed_bounds,\n    resolve_mode,\n    srgb_to_linear,\n)\nfrom comfy_extras.color_util import hex_to_rgb\nfrom comfy_extras.nodes_bounding_boxes import boxes_from_input\nfrom nodes import MAX_RESOLUTION\nfrom typing_extensions import override\n\n\nMAX_LAYERS = 50\n\n\ndef document_items(doc) -> list[dict]:\n    if not isinstance(doc, dict):\n        return []\n    version = doc.get(\"version\")\n    if version is not None and version != 1:\n        raise ValueError(f\"LAYERS document version {version!r} is not supported\")\n    items = []\n    for item in doc.get(\"layers\") or []:\n        if not isinstance(item, dict):\n            continue\n        item_type = item.get(\"type\", \"raster\")\n        if item_type != \"raster\":\n            raise ValueError(f\"LAYERS item type {item_type!r} is not supported yet\")\n        if not isinstance(item.get(\"image\"), torch.Tensor):\n            continue\n        blend = item.get(\"blend_mode\")\n        if blend is not None and blend not in _LAYER_MODES:\n            raise ValueError(f\"LAYERS item blend_mode {blend!r} is not a known blend mode\")\n        items.append(item)\n    return sorted(items, key=lambda item: _int(item.get(\"z_index\"), 0))\n\n\ndef document_canvas(doc) -> tuple[int, int] | None:\n    if not isinstance(doc, dict):","sourceCodeStart":14,"sourceCodeEnd":50,"githubUrl":"https://github.com/Comfy-Org/ComfyUI/blob/1c6d8d45b3693bfbb32385b410d813a7fd6be216/comfy_extras/nodes_compositor.py#L14-L50","documentation":"The LAYERS document loader in nodes_compositor.py validates a `version` field on incoming layer documents and only supports version 1 (a missing version is tolerated and treated as 1). Any other value (2, '1.0', 1.5, etc.) raises this ValueError so that documents from a newer or unrecognized schema fail loudly instead of being silently misinterpreted.","triggerScenarios":"Feeding a LAYERS dict/JSON where doc['version'] is anything other than the integer 1, e.g. 2, \"1\", or 1.0. Note the string \"1\" also fails because the check is `version != 1` without type coercion.","commonSituations":"Documents exported by a newer editor/frontend that bumped the schema version; hand-authored JSON where version was written as a string; a copy of a document that was partially migrated.","solutions":["Set \"version\": 1 (integer, not string) in the document, or omit the field entirely.","If the document genuinely uses a newer schema, downgrade/re-export it as version 1 with only raster layers.","Check that upstream tooling writing the LAYERS document emits an int, not \"1\"."],"exampleFix":"// before\n{\"version\": \"1\", \"layers\": [...]}\n// after\n{\"version\": 1, \"layers\": [...]}","handlingStrategy":"type-guard","validationCode":"def check_doc(doc):\n    v = doc.get(\"version\", 1)\n    if v is not None and v != 1:\n        doc = dict(doc)\n        doc[\"version\"] = 1  # only if you have verified schema compatibility\n    return doc","typeGuard":"def is_v1_layers_doc(doc) -> bool:\n    return isinstance(doc, dict) and doc.get(\"version\", 1) in (None, 1)","tryCatchPattern":"try:\n    items = document_items(doc)\nexcept ValueError as e:\n    if \"version\" in str(e):\n        raise UnsupportedDocumentVersion(e) from e\n    raise","preventionTips":["Emit \"version\": 1 as an int when writing LAYERS documents.","Pin the schema version in your exporter and test round-trips.","Treat version mismatch as a migration task, not something to silence."],"tags":["validation","layers-document","schema-version","comfyui"],"backgroundTag":null,"analyzedSha":"1c6d8d45b3693bfbb32385b410d813a7fd6be216","analyzedAt":"2026-08-14T19:37:18.893Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}