Comfy-Org/ComfyUI · error · ValueError

LAYERS item blend_mode {blend!r} is not a known blend mode

Error message

LAYERS item blend_mode {blend!r} is not a known blend mode

What it means

Each layer item may optionally carry a `blend_mode`; if present it must be a key of `_LAYER_MODES` (the compositor's known blend modes such as 'normal'). An unrecognized string (typo, different naming convention like 'multiply' vs 'mul', or a mode the compositor never implemented) raises this error rather than silently defaulting to normal.

Source

Thrown at comfy_extras/nodes_compositor.py:44

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):
        return None
    canvas = doc.get("canvas")
    if not isinstance(canvas, (tuple, list)) or len(canvas) != 2:
        return None
    w, h = _int(canvas[0], 0), _int(canvas[1], 0)
    return (w, h) if w > 0 and h > 0 else None


def _int(value, default: int) -> int:
    return int(value) if isinstance(value, (int, float)) and not isinstance(value, bool) else default

View on GitHub (pinned to 1c6d8d45b3)

Solutions

1. Check _LAYER_MODES in nodes_compositor.py for the accepted names and use exactly one of them.
2. Use lowercase names with underscores as the compositor expects (e.g. "normal", "multiply").
3. Omit blend_mode or set it to null when normal blending is intended.

Example fix

// before
{"blend_mode": "Multiply"}
// after
{"blend_mode": "multiply"}

KNOWN_MODES = {"normal", "multiply"}  # mirror _LAYER_MODES keys
def sanitize_blend(doc):
    for l in doc.get("layers") or []:
        b = l.get("blend_mode")
        if b is not None and b not in KNOWN_MODES:
            l["blend_mode"] = "normal"
    return doc

def is_known_blend(mode) -> bool:
    return mode is None or mode in _LAYER_MODES

When it happens

Trigger: Passing "blend_mode": "Multiply" (capitalized), "multiply " (trailing space), "src-over", or any mode name not in _LAYER_MODES on a layer item. `blend` set to None is allowed and means normal.

Common situations: Translating blend mode names from Photoshop/CSS conventions (e.g. 'linear-burn', 'color-dodge' with hyphens) into a compositor that expects a fixed vocabulary; typos when hand-writing layer JSON.

Related errors

• LAYERS document version {version!r} is not supported
• LAYERS item type {item_type!r} is not supported yet
• 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/6bcf8014efef8215. Report an issue: GitHub.