unslothai/unsloth · error · ValueError

reference_images require an input image (init_image).

Error message

reference_images require an input image (init_image).

What it means

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.

Source

Thrown at studio/backend/core/inference/diffusion.py:5348

                        )

                # Apply/adjust LoRA before picking the workflow pipe; from_pipe pipes share the transformer.
                self._apply_loras(state, loras, cancel)

                # Select the workflow pipe: txt2img uses the loaded pipe; img2img/inpaint reuse its modules via from_pipe.
                pipe = state.pipe
                init_pil = mask_pil = None
                control_pil = None
                cn_scale = cn_gstart = cn_gend = cn_mode = None
                ref_extra: list = []
                # Validate dependencies up front: mask/upscale/reference need an input image, and reference needs a supporting family.
                if init_image is None:
                    if mask_image is not None:
                        raise ValueError("mask_image requires an input image (init_image).")
                    if upscale is not None and upscale > 1.0:
                        raise ValueError("upscale requires an input image (init_image).")
                    if reference_images:
                        raise ValueError("reference_images require an input image (init_image).")
                if reference_images and not getattr(state.family, "reference", False):
                    raise ValueError(
                        f"Reference images are not supported for the '{state.family.name}' "
                        "model family."
                    )
                if getattr(state.family, "edit", False):
                    # Instruction editing: the loaded pipe IS the edit pipeline and always needs an input image; the prompt is the instruction.
                    if init_image is None:
                        raise ValueError(
                            f"{state.family.name} is an image-editing model: provide an input image."
                        )
                    if mask_image is not None:
                        # The edit family has no inpaint pipeline; a mask would be silently dropped.
                        raise ValueError(
                            f"{state.family.name} is an image-editing model and does not "
                            "support masks (mask_image)."
                        )
                    workflow = "edit"

View on GitHub (pinned to 203007d190)

Solutions

  1. Include init_image alongside reference_images in the request.
  2. Validate client-side: block submit when references are attached but no base image exists.
  3. If txt2img was intended, omit reference_images.

Example fix

# before
diffusion.generate(prompt="...", reference_images=[ref_b64])  # no init_image
# after
diffusion.generate(prompt="...", init_image=img_b64, reference_images=[ref_b64])
Defensive patterns

Strategy: validation

Validate before calling

if reference_images and init_image is None:
    raise ValueError("reference_images require init_image")  # client-side pre-check
diffusion.generate(prompt=p, init_image=init_image, reference_images=reference_images)

Type guard

def valid_reference_request(init_image, reference_images) -> bool:
    """References may only be attached alongside a base input image."""
    return not reference_images or init_image is not None

Try / catch

try:
    diffusion.generate(**params)
except ValueError as e:
    if "reference_images require an input image" in str(e):
        params.pop("reference_images")
        return diffusion.generate(**params)
    raise

Prevention

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of unslothai/unsloth@203007d190 (2026-08-15). Data as JSON: /api/errors/79bc8492fa22c241. Report an issue: GitHub.