unslothai/unsloth · error · ValueError

Reference images are not supported for the '{state.family.na

Error message

Reference images are not supported for the '{state.family.name}' model family.

What it means

Thrown by the diffusion generate path when the request includes reference_images but the currently loaded model family does not set the 'reference' capability flag (e.g. a plain SD/FLUX txt2img family vs. FLUX.2 with reference conditioning). It is an up-front ValueError so the route can map it to HTTP 400 instead of silently dropping the reference images later. The check runs before any pipeline work, so nothing is downloaded or loaded.

Source

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

                # 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"
                    init_pil = decode_b64_image(init_image, mode = "RGB")
                elif mask_image is not None and init_image is not None:

View on GitHub (pinned to 203007d190)

Solutions

Remove reference_images from the request, or clear the reference image in the UI before generating.
Load a model whose family supports reference conditioning (a family with reference=True, e.g. FLUX.2 reference) and retry the same request.
If you maintain family definitions, verify state.family.reference is set for the family you expect to accept references.

Example fix

// before
{"prompt": "a cat", "reference_images": ["data:image/png;base64,..."]}
// after (on a non-reference family)
{"prompt": "a cat in the style of the attached photo"}
// after (switch model first)
POST /images/load {"repo_id": "<flux2-reference-family-model>"} then resend the original payload

Defensive patterns

Strategy: validation

Validate before calling

def can_reference(family) -> bool:
    return bool(getattr(family, "reference", False))

# before the call
if reference_images and not can_reference(loaded_family):
    raise UserError("Clear the reference image or load a reference-capable model (e.g. FLUX.2).")

Type guard

def is_reference_family(family) -> bool:
    return bool(getattr(family, "reference", False))

Try / catch

try:
    result = engine.generate(prompt=p, reference_images=refs, init_image=img)
except ValueError as e:
    if "Reference images are not supported" in str(e):
        # 400-class: surface to user, do not retry
        notify_user(str(e))
    else:
        raise

Prevention

Filter reference_images out of the payload automatically when the loaded family lacks the reference flag.
Show the reference-image control only for reference-capable families in the UI.
Reset per-family attachments (reference, mask, CN) whenever the loaded model changes.

When it happens

Trigger: POST to the image-generation endpoint with reference_images set while the loaded model family lacks family.reference=True (getattr(state.family, 'reference', False) is falsy). Also fires when reference_images is combined with init_image on a non-reference family, since the init_image requirement is checked separately.

Common situations: Switching the UI/model from FLUX.2 (reference-capable) to a SDXL or FLUX.1 checkpoint while a reference image is still attached in the request payload; hand-written API clients copying a FLUX.2 payload shape against a different loaded model.

Related errors

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