invoke-ai/InvokeAI · error · ValueError

Unable to load pixels from subject image

Error message

Unable to load pixels from subject image

What it means

After resolving the chroma key color, invoke() calls image_subject.load() to get the pixel-access buffer for the per-pixel distance loop. PIL returns None if pixel access cannot be established; the node raises instead of crashing with a TypeError inside the loop.

Source

Thrown at invokeai/app/invocations/composition-nodes.py:1336

        if image_background.height == 0 or image_background.width == 0:
            raise ValueError("The subject image has zero height or width")

        # Handle backdrop removal:
        chroma_key = self.chroma_key.strip()
        if 0 < len(chroma_key):
            # Remove pixels by chroma key:
            if chroma_key[0] == "(":
                chroma_key = tuple_from_string(chroma_key)
                while len(chroma_key) < 3:
                    chroma_key = tuple(list(chroma_key) + [0])
                if len(chroma_key) == 3:
                    chroma_key = tuple(list(chroma_key) + [255])
            else:
                chroma_key = ImageColor.getcolor(chroma_key, "RGBA")
            threshold = self.threshold**2.0  # to compare vs squared color distance from key
            pixels = image_subject.load()
            if pixels is None:
                raise ValueError("Unable to load pixels from subject image")
            for i in range(image_subject.width):
                for j in range(image_subject.height):
                    if (
                        reduce(
                            lambda a, b: a + b, [(pixels[i, j][k] - chroma_key[k]) ** 2 for k in range(len(chroma_key))]
                        )
                        < threshold
                    ):
                        pixels[i, j] = tuple([0 for k in range(len(chroma_key))])
        else:
            # Remove pixels by flood select from corners:
            ImageDraw.floodfill(image_subject, (0, 0), (0, 0, 0, 0), thresh=self.threshold)
            ImageDraw.floodfill(image_subject, (0, image_subject.height - 1), (0, 0, 0, 0), thresh=self.threshold)
            ImageDraw.floodfill(image_subject, (image_subject.width - 1, 0), (0, 0, 0, 0), thresh=self.threshold)
            ImageDraw.floodfill(
                image_subject, (image_subject.width - 1, image_subject.height - 1), (0, 0, 0, 0), thresh=self.threshold
            )

View on GitHub (pinned to 0b6a024f2f)

Solutions

1. Re-generate/re-upload the subject image and retry.
2. Convert the image explicitly before the node (e.g. img.convert('RGBA')) to ensure a loadable pixel buffer.
3. Update Pillow to a recent version; check available memory if the image is very large.

Example fix

# before
pixels = image_subject.load()  # None for corrupt image
# after
image_subject = image_subject.convert("RGBA")
pixels = image_subject.load()
if pixels is None:
    raise ValueError("re-generate the subject image")

pixels = image_subject.load()
if pixels is None:
    raise ValueError("subject image pixel buffer unavailable; regenerate image")

try:
    output = node.invoke(context)
except ValueError as e:
    if "Unable to load pixels" in str(e):
        image = reencode_image(context.images.get_pil(name).convert("RGBA"))
        retry_composition(image)
    else:
        raise

When it happens

Trigger: invoke() with chroma key configured, where image_subject.load() returns None (PIL could not allocate/access the pixel buffer for the image).

Common situations: Degenerate or corrupt image data in the image store; exotic image modes that failed RGBA conversion; very large images exhausting memory during pixel-access initialization.

Related errors

• The subject image has zero height or width

AI-assisted analysis of invoke-ai/InvokeAI@0b6a024f2f (2026-08-29). Data as JSON: /api/errors/2ea36d746a7675af. Report an issue: GitHub.