unslothai/unsloth · error · ValueError

upscale requires an input image (init_image).

Error message

upscale requires an input image (init_image).

What it means

Up-front dependency validation in generate(): an `upscale` factor greater than 1.0 requires an `init_image` to upscale -- upscaling is an image-conditioned operation, not a txt2img parameter. Checked in the same early validation block (init_image is None and upscale is not None and upscale > 1.0), raising a clean ValueError before any pipeline work.

Source

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

                            "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(
                            f"{state.family.name} is an image-editing model and does not "
                            "support masks (mask_image)."

View on GitHub (pinned to 203007d190)

Solutions

  1. Provide init_image when requesting upscale > 1.0.
  2. If higher-resolution generation was intended, raise width/height instead of using upscale.
  3. Clear upscale (set to None or 1.0) on txt2img requests client-side.

Example fix

# before
diffusion.generate(prompt="...", upscale=2.0)  # no init_image
# after: higher-res generation, no input image needed
diffusion.generate(prompt="...", width=2048, height=2048)
Defensive patterns

Strategy: validation

Validate before calling

if upscale is not None and upscale > 1.0 and init_image is None:
    upscale = None  # or raise client-side: upscale needs a source image
diffusion.generate(prompt=p, upscale=upscale)

Type guard

def valid_upscale_request(init_image, upscale) -> bool:
    """Upscale only applies to an input image."""
    return upscale is None or upscale <= 1.0 or init_image is not None

Try / catch

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

Prevention

When it happens

Trigger: Calling generate() with `upscale=2.0` (or any value > 1.0) while `init_image` is None. Values of None or <= 1.0 do not trigger it.

Common situations: UI upscale toggle persisted from a previous img2img session applied to a fresh txt2img request; API clients passing upscale unconditionally; users expecting upscale to mean 'generate at higher resolution' rather than 'upscale the input image'.

Related errors

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