{"record":{"id":"2dbaf2705a3355c6","repo":"unslothai/unsloth","slug":"img2img-inpaint-reference-upscale-are-not-ye","errorCode":null,"errorMessage":"img2img / inpaint / reference / upscale are not yet supported on the native sd.cpp engine; run on a GPU (diffusers) for image-conditioned workflows.","messagePattern":"img2img / inpaint / reference / upscale are not yet supported on the native sd\\.cpp engine; run on a GPU \\(diffusers\\) for image-conditioned workflows\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"studio/backend/core/inference/sd_cpp_backend.py","lineNumber":2060,"sourceCode":"        reference_images: Optional[list[str]] = None,  # GPU/diffusers-only (FLUX.2)\n        # LoRA (id, weight) pairs; resolved up front then applied per path: prompt tags for one-shot sd-cli, structured `lora` for sd-server.\n        loras: Optional[list[tuple[str, float]]] = None,\n        # ControlNet is diffusers-only; rejected by the guard below (accepted for parity).\n        controlnet: Optional[tuple[str, str, str, float, float, float]] = None,\n    ) -> dict[str, Any]:\n        import tempfile\n\n        from PIL import Image\n\n        from core.inference import diffusion_lora\n\n        if (\n            init_image is not None\n            or mask_image is not None\n            or reference_images\n            or (upscale is not None and upscale > 1)\n        ):\n            raise ValueError(\n                \"img2img / inpaint / reference / upscale are not yet supported on the native \"\n                \"sd.cpp engine; run on a GPU (diffusers) for image-conditioned workflows.\"\n            )\n        if prompts is not None or seeds is not None:\n            raise ValueError(\n                \"Batched prompt/seed lists are not supported on the native sd.cpp engine \"\n                \"(it renders serially); run on a GPU (diffusers) for batched generation, \"\n                \"or use batch_size for a serial native batch.\"\n            )\n        # strength 0/None disables ControlNet (matches diffusers), so no-op it rather than 400.\n        if controlnet is not None and controlnet[3] in (None, 0, 0.0):\n            controlnet = None\n        if controlnet is not None:\n            raise ValueError(\n                \"ControlNet is not yet supported on the native sd.cpp engine; run on a GPU \"\n                \"(diffusers) for ControlNet conditioning.\"\n            )\n","sourceCodeStart":2042,"sourceCodeEnd":2078,"githubUrl":"https://github.com/unslothai/unsloth/blob/203007d19051dcd2ae33876786d117c99f6b0368/studio/backend/core/inference/sd_cpp_backend.py#L2042-L2078","documentation":"ValueError at the top of native generate: the sd.cpp engine implements text-to-image only. init_image, mask_image, reference_images, or upscale>1 request image-conditioned workflows (img2img/inpaint/reference/upscale) that the native engine cannot run, so it fails fast with a pointer to the diffusers engine on GPU.","triggerScenarios":"generate() on the native engine with init_image, mask_image, non-empty reference_images, or upscale > 1.","commonSituations":"Hosts without GPU falling back to sd.cpp while the UI still offers inpaint/img2img; API clients reusing a diffusers request payload against the native engine.","solutions":["Route image-conditioned requests to the diffusers engine on a GPU host.","Drop init_image/mask_image/reference_images and set upscale<=1 for native text-to-image.","For plain upscaling of a generated image, do a separate post-process step outside the engine."],"exampleFix":"# before (native engine)\nbackend.generate(prompt='a cat', init_image=img)\n\n# after\nbackend.generate(prompt='a cat')  # native t2i; use diffusers engine for img2img","handlingStrategy":"validation","validationCode":"def is_image_conditioned(init_image, mask_image, reference_images, upscale) -> bool:\n    return (init_image is not None or mask_image is not None\n            or bool(reference_images) or (upscale is not None and upscale > 1))\n\nif is_image_conditioned(init_image, mask_image, reference_images, upscale):\n    route_to_diffusers_engine(request)","typeGuard":"def is_native_compatible_request(req: dict) -> bool:\n    return req.get('init_image') is None and req.get('mask_image') is None \\\n        and not req.get('reference_images') and (req.get('upscale') or 1) <= 1","tryCatchPattern":null,"preventionTips":["Branch on request shape before choosing the engine: image inputs imply diffusers.","Hide img2img/inpaint/upscale controls in the UI when the native engine is active."],"tags":["capability","validation","img2img","sd-cpp"],"backgroundTag":null,"analyzedSha":"203007d19051dcd2ae33876786d117c99f6b0368","analyzedAt":"2026-08-15T02:48:39.846Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}