Comfy-Org/ComfyUI · error · ValueError

LAYERS document version {version!r} is not supported

Error message

LAYERS document version {version!r} is not supported

What it means

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.

Source

Thrown at comfy_extras/nodes_compositor.py:32

    placed_bounds,
    resolve_mode,
    srgb_to_linear,
)
from comfy_extras.color_util import hex_to_rgb
from comfy_extras.nodes_bounding_boxes import boxes_from_input
from nodes import MAX_RESOLUTION
from typing_extensions import override


MAX_LAYERS = 50


def document_items(doc) -> list[dict]:
    if not isinstance(doc, dict):
        return []
    version = doc.get("version")
    if version is not None and version != 1:
        raise ValueError(f"LAYERS document version {version!r} is not supported")
    items = []
    for item in doc.get("layers") or []:
        if not isinstance(item, dict):
            continue
        item_type = item.get("type", "raster")
        if item_type != "raster":
            raise ValueError(f"LAYERS item type {item_type!r} is not supported yet")
        if not isinstance(item.get("image"), torch.Tensor):
            continue
        blend = item.get("blend_mode")
        if blend is not None and blend not in _LAYER_MODES:
            raise ValueError(f"LAYERS item blend_mode {blend!r} is not a known blend mode")
        items.append(item)
    return sorted(items, key=lambda item: _int(item.get("z_index"), 0))


def document_canvas(doc) -> tuple[int, int] | None:
    if not isinstance(doc, dict):

View on GitHub (pinned to 1c6d8d45b3)

Solutions

1. Set "version": 1 (integer, not string) in the document, or omit the field entirely.
2. If the document genuinely uses a newer schema, downgrade/re-export it as version 1 with only raster layers.
3. Check that upstream tooling writing the LAYERS document emits an int, not "1".

Example fix

// before
{"version": "1", "layers": [...]}
// after
{"version": 1, "layers": [...]}

def check_doc(doc):
    v = doc.get("version", 1)
    if v is not None and v != 1:
        doc = dict(doc)
        doc["version"] = 1  # only if you have verified schema compatibility
    return doc

def is_v1_layers_doc(doc) -> bool:
    return isinstance(doc, dict) and doc.get("version", 1) in (None, 1)

try:
    items = document_items(doc)
except ValueError as e:
    if "version" in str(e):
        raise UnsupportedDocumentVersion(e) from e
    raise

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• LAYERS item type {item_type!r} is not supported yet
• LAYERS item blend_mode {blend!r} is not a known blend mode
• INVALID_TAG_FILTER
• Connect at least one keyframe image.
• Spreading {len(images)} images across the clip needs an expl

AI-assisted analysis of Comfy-Org/ComfyUI@1c6d8d45b3 (2026-08-14). Data as JSON: /api/errors/1586b25afe5d6876. Report an issue: GitHub.