unslothai/unsloth · error · ValueError

mask_image requires an input image (init_image).

Error message

mask_image requires an input image (init_image).

What it means

Up-front dependency validation in generate(): a `mask_image` (for inpainting) only makes sense with an `init_image` to mask. The code validates all input-image dependencies before touching device objects or building workflow pipes, raising a clean ValueError when init_image is None but mask_image was supplied. Failing early avoids loading an inpaint pipeline for an impossible request.

Source

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

                    except Exception as exc:  # noqa: BLE001 — speed is best-effort
                        logger.warning(
                            "diffusion.speed: deferred engagement failed, staying eager: %s",
                            exc,
                        )

                # 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(

View on GitHub (pinned to 203007d190)

Solutions

1. Include init_image whenever mask_image is provided.
2. Validate the request client-side: assert init_image is present if mask_image is.
3. If pure txt2img was intended, remove mask_image from the call.

Example fix

# before
diffusion.generate(prompt="...", mask_image=mask_b64)  # no init_image
# after
diffusion.generate(prompt="...", init_image=img_b64, mask_image=mask_b64)

if mask_image is not None and init_image is None:
    raise ValueError("mask_image requires init_image")  # fail client-side, before the API
diffusion.generate(prompt=p, init_image=init_image, mask_image=mask_image)

def valid_mask_request(init_image, mask_image) -> bool:
    """A mask may only accompany an init image."""
    return mask_image is None or init_image is not None

try:
    diffusion.generate(**params)
except ValueError as e:
    if "mask_image requires an input image" in str(e):
        params.pop("mask_image")
        return diffusion.generate(**params)  # degrade to plain generation
    raise

When it happens

Trigger: Calling generate() with `mask_image` set (base64 control/mask input) while `init_image` is None; the first branch of the `if init_image is None:` validation block fires.

Common situations: Frontend sending the mask from a canvas but dropping the init image on serialization; clients copying an inpaint payload and deleting the init_image field; partial multipart uploads where the image part fails but the mask part arrives.

Related errors

• upscale requires an input image (init_image).
• reference_images require an input image (init_image).
• {state.family.name} is an image-editing model and does not s
• Unknown model_kind '{model_kind}'. Expected one of {sorted(_
• Invalid base64 image data: {exc}

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