{"record":{"id":"810fe96fdb825608","repo":"invoke-ai/InvokeAI","slug":"the-subject-image-has-zero-height-or-width","errorCode":null,"errorMessage":"The subject image has zero height or width","messagePattern":"The subject image has zero height or width","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"invokeai/app/invocations/composition-nodes.py","lineNumber":1317,"sourceCode":"    \"\"\"Removes backdrop from subject image then overlays subject on background image. Originally created by @dwringer\"\"\"\n\n    image_subject: ImageField = InputField(description=\"Image of the subject on a plain monochrome background\")\n    image_background: ImageField = InputField(description=\"Image of a background scene\")\n    chroma_key: str = InputField(\n        default=\"\", description=\"Can be empty for corner flood select, or CSS-3 color or tuple\"\n    )\n    threshold: int = InputField(ge=0, default=50, description=\"Subject isolation flood-fill threshold\")\n    fill_x: bool = InputField(default=False, description=\"Scale base subject image to fit background width\")\n    fill_y: bool = InputField(default=True, description=\"Scale base subject image to fit background height\")\n    x_offset: int = InputField(default=0, description=\"x-offset for the subject\")\n    y_offset: int = InputField(default=0, description=\"y-offset for the subject\")\n\n    def invoke(self, context: InvocationContext) -> ImageOutput:\n        image_background = context.images.get_pil(self.image_background.image_name).convert(mode=\"RGBA\")\n        image_subject = context.images.get_pil(self.image_subject.image_name).convert(mode=\"RGBA\")\n\n        if image_subject.height == 0 or image_subject.width == 0:\n            raise ValueError(\"The subject image has zero height or width\")\n        if image_background.height == 0 or image_background.width == 0:\n            raise ValueError(\"The subject image has zero height or width\")\n\n        # Handle backdrop removal:\n        chroma_key = self.chroma_key.strip()\n        if 0 < len(chroma_key):\n            # Remove pixels by chroma key:\n            if chroma_key[0] == \"(\":\n                chroma_key = tuple_from_string(chroma_key)\n                while len(chroma_key) < 3:\n                    chroma_key = tuple(list(chroma_key) + [0])\n                if len(chroma_key) == 3:\n                    chroma_key = tuple(list(chroma_key) + [255])\n            else:\n                chroma_key = ImageColor.getcolor(chroma_key, \"RGBA\")\n            threshold = self.threshold**2.0  # to compare vs squared color distance from key\n            pixels = image_subject.load()\n            if pixels is None:","sourceCodeStart":1299,"sourceCodeEnd":1335,"githubUrl":"https://github.com/invoke-ai/InvokeAI/blob/0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06/invokeai/app/invocations/composition-nodes.py#L1299-L1335","documentation":"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.","triggerScenarios":"Chroma-key/composite node invoked with image_subject whose loaded PIL image has height == 0 or width == 0.","commonSituations":"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.","solutions":["Fix the upstream node so it outputs a non-empty subject image.","Verify the subject image's dimensions before queueing the graph.","Re-upload/re-generate the subject image if the stored file is corrupt."],"exampleFix":"# before\nimg = context.images.get_pil(name)  # 0-height\ncrop = img.crop((10, 10, 10, 20))   # produces zero-width image\n# after\nbox = (10, 10, 30, 20)\nassert box[2] > box[0] and box[3] > box[1]\ncrop = img.crop(box)","handlingStrategy":"validation","validationCode":"subject = context.images.get_pil(node.image_subject.image_name)\nif subject.width == 0 or subject.height == 0:\n    raise ValueError(\"regenerate subject image: zero dimensions\")","typeGuard":null,"tryCatchPattern":"try:\n    output = node.invoke(context)\nexcept ValueError as e:\n    if \"zero height or width\" in str(e):\n        regenerate_upstream_image()\n        output = node.invoke(context)\n    else:\n        raise","preventionTips":["Validate crop/resize boxes upstream so area > 0","Check image dimensions after every transform node","Guard against placeholder/never-initialized image records"],"tags":["images","validation","composition"],"backgroundTag":"invalid-image-dimensions","analyzedSha":"0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06","analyzedAt":"2026-08-29T04:46:49.967Z","schemaVersion":2},"datasetVersion":"2026-08-29T07:17:48.351Z"}