{"record":{"id":"79bc8492fa22c241","repo":"unslothai/unsloth","slug":"reference-images-require-an-input-image-init-imag","errorCode":null,"errorMessage":"reference_images require an input image (init_image).","messagePattern":"reference_images require an input image \\(init_image\\)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":400,"severity":"error","filePath":"studio/backend/core/inference/diffusion.py","lineNumber":5348,"sourceCode":"                        )\n\n                # Apply/adjust LoRA before picking the workflow pipe; from_pipe pipes share the transformer.\n                self._apply_loras(state, loras, cancel)\n\n                # Select the workflow pipe: txt2img uses the loaded pipe; img2img/inpaint reuse its modules via from_pipe.\n                pipe = state.pipe\n                init_pil = mask_pil = None\n                control_pil = None\n                cn_scale = cn_gstart = cn_gend = cn_mode = None\n                ref_extra: list = []\n                # Validate dependencies up front: mask/upscale/reference need an input image, and reference needs a supporting family.\n                if init_image is None:\n                    if mask_image is not None:\n                        raise ValueError(\"mask_image requires an input image (init_image).\")\n                    if upscale is not None and upscale > 1.0:\n                        raise ValueError(\"upscale requires an input image (init_image).\")\n                    if reference_images:\n                        raise ValueError(\"reference_images require an input image (init_image).\")\n                if reference_images and not getattr(state.family, \"reference\", False):\n                    raise ValueError(\n                        f\"Reference images are not supported for the '{state.family.name}' \"\n                        \"model family.\"\n                    )\n                if getattr(state.family, \"edit\", False):\n                    # Instruction editing: the loaded pipe IS the edit pipeline and always needs an input image; the prompt is the instruction.\n                    if init_image is None:\n                        raise ValueError(\n                            f\"{state.family.name} is an image-editing model: provide an input image.\"\n                        )\n                    if mask_image is not None:\n                        # The edit family has no inpaint pipeline; a mask would be silently dropped.\n                        raise ValueError(\n                            f\"{state.family.name} is an image-editing model and does not \"\n                            \"support masks (mask_image).\"\n                        )\n                    workflow = \"edit\"","sourceCodeStart":5330,"sourceCodeEnd":5366,"githubUrl":"https://github.com/unslothai/unsloth/blob/203007d19051dcd2ae33876786d117c99f6b0368/studio/backend/core/inference/diffusion.py#L5330-L5366","documentation":"Up-front dependency validation in generate(): `reference_images` (image conditioning assets) require an `init_image` as the base input. Part of the same early validation block that enforces input-image dependencies (mask/upscale/reference) before any device or pipeline work; a clean ValueError when reference_images is non-empty and init_image is None.","triggerScenarios":"Calling generate() with a non-empty `reference_images` list while `init_image` is None. Note a separate, adjacent check also rejects reference_images entirely when the family lacks `reference` support -- this error is specifically the missing-init_image case.","commonSituations":"Clients attaching style/product reference photos without a base image; UI reference-image panel allowing submission without a source image; API integrations mapping optional fields where init_image got dropped but references survived.","solutions":["Include init_image alongside reference_images in the request.","Validate client-side: block submit when references are attached but no base image exists.","If txt2img was intended, omit reference_images."],"exampleFix":"# before\ndiffusion.generate(prompt=\"...\", reference_images=[ref_b64])  # no init_image\n# after\ndiffusion.generate(prompt=\"...\", init_image=img_b64, reference_images=[ref_b64])","handlingStrategy":"validation","validationCode":"if reference_images and init_image is None:\n    raise ValueError(\"reference_images require init_image\")  # client-side pre-check\ndiffusion.generate(prompt=p, init_image=init_image, reference_images=reference_images)","typeGuard":"def valid_reference_request(init_image, reference_images) -> bool:\n    \"\"\"References may only be attached alongside a base input image.\"\"\"\n    return not reference_images or init_image is not None","tryCatchPattern":"try:\n    diffusion.generate(**params)\nexcept ValueError as e:\n    if \"reference_images require an input image\" in str(e):\n        params.pop(\"reference_images\")\n        return diffusion.generate(**params)\n    raise","preventionTips":["Block submit when references exist without a base image.","Also check the family's `reference` capability flag -- a separate error covers unsupported families.","Map optional image fields carefully in API clients so init_image is never silently dropped."],"tags":["diffusion","reference-images","validation","request-payload"],"backgroundTag":null,"analyzedSha":"203007d19051dcd2ae33876786d117c99f6b0368","analyzedAt":"2026-08-15T02:48:39.846Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}