{"record":{"id":"6bcf8014efef8215","repo":"Comfy-Org/ComfyUI","slug":"layers-item-blend-mode-blend-r-is-not-a-known-bl","errorCode":null,"errorMessage":"LAYERS item blend_mode {blend!r} is not a known blend mode","messagePattern":"LAYERS item blend_mode (.+?) is not a known blend mode","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"comfy_extras/nodes_compositor.py","lineNumber":44,"sourceCode":"\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):\n        return None\n    canvas = doc.get(\"canvas\")\n    if not isinstance(canvas, (tuple, list)) or len(canvas) != 2:\n        return None\n    w, h = _int(canvas[0], 0), _int(canvas[1], 0)\n    return (w, h) if w > 0 and h > 0 else None\n\n\ndef _int(value, default: int) -> int:\n    return int(value) if isinstance(value, (int, float)) and not isinstance(value, bool) else default\n\n","sourceCodeStart":26,"sourceCodeEnd":62,"githubUrl":"https://github.com/Comfy-Org/ComfyUI/blob/1c6d8d45b3693bfbb32385b410d813a7fd6be216/comfy_extras/nodes_compositor.py#L26-L62","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check _LAYER_MODES in nodes_compositor.py for the accepted names and use exactly one of them.","Use lowercase names with underscores as the compositor expects (e.g. \"normal\", \"multiply\").","Omit blend_mode or set it to null when normal blending is intended."],"exampleFix":"// before\n{\"blend_mode\": \"Multiply\"}\n// after\n{\"blend_mode\": \"multiply\"}","handlingStrategy":"validation","validationCode":"KNOWN_MODES = {\"normal\", \"multiply\"}  # mirror _LAYER_MODES keys\ndef sanitize_blend(doc):\n    for l in doc.get(\"layers\") or []:\n        b = l.get(\"blend_mode\")\n        if b is not None and b not in KNOWN_MODES:\n            l[\"blend_mode\"] = \"normal\"\n    return doc","typeGuard":"def is_known_blend(mode) -> bool:\n    return mode is None or mode in _LAYER_MODES","tryCatchPattern":null,"preventionTips":["Read _LAYER_MODES from nodes_compositor.py and use only those exact strings.","Normalize casing/underscores when translating from CSS or Photoshop names.","Prefer omitting blend_mode when normal blending is intended."],"tags":["validation","layers-document","blend-mode","comfyui"],"backgroundTag":null,"analyzedSha":"1c6d8d45b3693bfbb32385b410d813a7fd6be216","analyzedAt":"2026-08-14T19:37:18.893Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}