invoke-ai/InvokeAI · error · ValueError

The subject image has zero height or width

Error message

The subject image has zero height or width

What it means

In this image-composition invocation, invoke() loads the subject and background images as RGBA and rejects a subject image with zero height or width before any compositing. A PIL image with a zero dimension cannot participate in the chroma-key/composite math.

Source

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

    """Removes backdrop from subject image then overlays subject on background image. Originally created by @dwringer"""

    image_subject: ImageField = InputField(description="Image of the subject on a plain monochrome background")
    image_background: ImageField = InputField(description="Image of a background scene")
    chroma_key: str = InputField(
        default="", description="Can be empty for corner flood select, or CSS-3 color or tuple"
    )
    threshold: int = InputField(ge=0, default=50, description="Subject isolation flood-fill threshold")
    fill_x: bool = InputField(default=False, description="Scale base subject image to fit background width")
    fill_y: bool = InputField(default=True, description="Scale base subject image to fit background height")
    x_offset: int = InputField(default=0, description="x-offset for the subject")
    y_offset: int = InputField(default=0, description="y-offset for the subject")

    def invoke(self, context: InvocationContext) -> ImageOutput:
        image_background = context.images.get_pil(self.image_background.image_name).convert(mode="RGBA")
        image_subject = context.images.get_pil(self.image_subject.image_name).convert(mode="RGBA")

        if image_subject.height == 0 or image_subject.width == 0:
            raise ValueError("The subject image has zero height or width")
        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:

View on GitHub (pinned to 0b6a024f2f)

Solutions

  1. Fix the upstream node so it outputs a non-empty subject image.
  2. Verify the subject image's dimensions before queueing the graph.
  3. Re-upload/re-generate the subject image if the stored file is corrupt.

Example fix

# before
img = context.images.get_pil(name)  # 0-height
crop = img.crop((10, 10, 10, 20))   # produces zero-width image
# after
box = (10, 10, 30, 20)
assert box[2] > box[0] and box[3] > box[1]
crop = img.crop(box)
Defensive patterns

Strategy: validation

Validate before calling

subject = context.images.get_pil(node.image_subject.image_name)
if subject.width == 0 or subject.height == 0:
    raise ValueError("regenerate subject image: zero dimensions")

Try / catch

try:
    output = node.invoke(context)
except ValueError as e:
    if "zero height or width" in str(e):
        regenerate_upstream_image()
        output = node.invoke(context)
    else:
        raise

Prevention

When it happens

Trigger: Chroma-key/composite node invoked with image_subject whose loaded PIL image has height == 0 or width == 0.

Common situations: An upstream node produced an empty/zero-size image (e.g. crop with zero-area box, failed resize); corrupted image stored in the image service; passing a placeholder image record that was never initialized.

Related errors

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