blend_modes imports but blending fails: inspect the image-array contract

Scope and symptoms

Separate a missing library from an operation receiving the wrong image representation. Channel count, numeric range and opacity deserve their own checks.

Search fragments; wording and context vary:

No module named 'blend_modes'

Source-supported context

The blend_modes documentation specifies requirements for its image arrays and opacity arguments, including floating-point RGBA data and its expected value range. Those requirements are not automatically the internal representation of every image node. V04-BLEND

Distinguish these cases

1. The package is missing and the node fails before registration.

2. Import works, but the function receives an incompatible shape, channel count or data type.

3. Blending runs but produces incorrect brightness or transparency because an adapter uses the wrong range or alpha interpretation.

Suggested diagnostic sequence

This sequence is editorial guidance, not a diagnosis of your machine.

1. Confirm the declared dependency and failing call in the node repository. Resolve a genuine import failure in the correct interpreter before inspecting pixels.

2. After import succeeds, record only the input array's shape, type, range and opacity value. Do not upload the user's images to diagnose those properties.

3. Compare each property with the called function's documentation and fix the node's conversion boundary. Adding an alpha channel requires a deliberate opacity or mask meaning rather than arbitrary values.

4. Test two simple images of equal size and a known opacity before restoring real inputs. Change one setting at a time and keep the original files unchanged.

Completion checks

The operation accepts valid input and produces the expected color and transparency on the test case. An exception-free result can still be numerically wrong.

Limits and cautions

Do not assume all ComfyUI image nodes use one array range. The specific adapter and library function determine the conversion; never overwrite original images as part of an experiment.

Source review: 2026-09-22. No installation, GPU inference or user-environment repair was executed.

Original sources

• blend_modes documentation · 2026-09-22

Related guides

• ModuleNotFoundError in ComfyUI even though the package is installed
• Keep a reproducible ComfyUI repair record without exposing secrets