{"record":{"id":"c700de16a466fab8","repo":"unslothai/unsloth","slug":"upscale-requires-an-input-image-init-image","errorCode":null,"errorMessage":"upscale requires an input image (init_image).","messagePattern":"upscale requires an input image \\(init_image\\)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":400,"severity":"error","filePath":"studio/backend/core/inference/diffusion.py","lineNumber":5346,"sourceCode":"                            \"diffusion.speed: deferred engagement failed, staying eager: %s\",\n                            exc,\n                        )\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).\"","sourceCodeStart":5328,"sourceCodeEnd":5364,"githubUrl":"https://github.com/unslothai/unsloth/blob/203007d19051dcd2ae33876786d117c99f6b0368/studio/backend/core/inference/diffusion.py#L5328-L5364","documentation":"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.","triggerScenarios":"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.","commonSituations":"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'.","solutions":["Provide init_image when requesting upscale > 1.0.","If higher-resolution generation was intended, raise width/height instead of using upscale.","Clear upscale (set to None or 1.0) on txt2img requests client-side."],"exampleFix":"# before\ndiffusion.generate(prompt=\"...\", upscale=2.0)  # no init_image\n# after: higher-res generation, no input image needed\ndiffusion.generate(prompt=\"...\", width=2048, height=2048)","handlingStrategy":"validation","validationCode":"if upscale is not None and upscale > 1.0 and init_image is None:\n    upscale = None  # or raise client-side: upscale needs a source image\ndiffusion.generate(prompt=p, upscale=upscale)","typeGuard":"def valid_upscale_request(init_image, upscale) -> bool:\n    \"\"\"Upscale only applies to an input image.\"\"\"\n    return upscale is None or upscale <= 1.0 or init_image is not None","tryCatchPattern":"try:\n    diffusion.generate(**params)\nexcept ValueError as e:\n    if \"upscale requires an input image\" in str(e):\n        params.pop(\"upscale\")\n        return diffusion.generate(**params)\n    raise","preventionTips":["Reset upscale state when the UI switches from img2img back to txt2img.","For higher-resolution txt2img, adjust width/height, not upscale.","Remember only upscale > 1.0 triggers the check."],"tags":["diffusion","upscale","validation","request-payload"],"backgroundTag":null,"analyzedSha":"203007d19051dcd2ae33876786d117c99f6b0368","analyzedAt":"2026-08-15T02:48:39.846Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}