{"record":{"id":"e78fde123b78a73f","repo":"unslothai/unsloth","slug":"controlnet-is-not-supported-for-this-model-quantis","errorCode":null,"errorMessage":"ControlNet is not supported for this model/quantisation on the diffusers engine (needs a bf16 or bnb-4bit load of a family with a ControlNet pipeline; not GGUF-via-diffusers or torchao fp8/int8).","messagePattern":"ControlNet is not supported for this model/quantisation on the diffusers engine \\(needs a bf16 or bnb-4bit load of a family with a ControlNet pipeline; not GGUF-via-diffusers or torchao fp8/int8\\)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":400,"severity":"error","filePath":"studio/backend/core/inference/diffusion.py","lineNumber":5433,"sourceCode":"                    # strength 0 disables CN: skip the whole path so a no-op never pays the download/VRAM.\n                    if cn_strength in (None, 0, 0.0):\n                        controlnet = None\n                    else:\n                        if workflow != \"txt2img\":\n                            raise ValueError(\n                                \"ControlNet currently combines with plain text-to-image only, not \"\n                                f\"the {workflow} workflow.\"\n                            )\n                        if not diffusion_controlnet.supports_controlnet(\n                            engine = \"diffusers\",\n                            family = state.family.name,\n                            has_controlnet_pipeline = bool(\n                                getattr(state.family, \"controlnet_pipeline_class\", None)\n                            ),\n                            model_kind = state.kind,\n                            transformer_quant = state.transformer_quant,\n                        ):\n                            raise ValueError(\n                                \"ControlNet is not supported for this model/quantisation on the \"\n                                \"diffusers engine (needs a bf16 or bnb-4bit load of a family with a \"\n                                \"ControlNet pipeline; not GGUF-via-diffusers or torchao fp8/int8).\"\n                            )\n                        # Decode + preprocess the control image FIRST so a bad image 400s before any CN download, at the OUTPUT size.\n                        src = decode_b64_image(cn_image_b64, mode = \"RGB\")\n                        control_pil = diffusion_controlnet.preprocess_control(src, cn_type).resize(\n                            (width, height), Image.LANCZOS\n                        )\n                        try:\n                            resolved_cn = diffusion_controlnet.resolve_controlnet(\n                                cn_id, family = state.family.name\n                            )\n                        except FileNotFoundError as exc:\n                            # An unknown CN id -> 400, not 500 (the route maps ValueError).\n                            raise ValueError(str(exc)) from exc\n                        pipe = self._controlnet_pipe(state, resolved_cn, cancel)\n                        workflow = \"controlnet\"","sourceCodeStart":5415,"sourceCodeEnd":5451,"githubUrl":"https://github.com/unslothai/unsloth/blob/203007d19051dcd2ae33876786d117c99f6b0368/studio/backend/core/inference/diffusion.py#L5415-L5451","documentation":"ControlNet on the diffusers engine requires the model to be loaded as bf16 or bnb-4bit, from a family that defines a ControlNet pipeline class, and not as GGUF-via-diffusers or torchao fp8/int8. supports_controlnet() checks engine, family, pipeline class availability, model kind and transformer quantisation; failure raises this ValueError (mapped to HTTP 400) before any ControlNet weights are downloaded.","triggerScenarios":"Requesting controlnet (non-zero strength, txt2img workflow) while the loaded model is a GGUF quant or torchao fp8/int8 build, or the family (e.g. FLUX.2 or a family without controlnet_pipeline_class) has no ControlNet pipeline in its definition.","commonSituations":"Running ControlNet against a memory-saving GGUF load; using a torchao-quantised checkpoint on constrained VRAM; picking a newer family whose curated catalog has no CN pipeline class yet.","solutions":["Reload the model in bf16 (full precision load) or bnb-4bit and retry the ControlNet request.","Verify the model family actually ships a ControlNet pipeline (check the family's controlnet_pipeline_class); switch to a supported family (e.g. SDXL/Flux CN-supported) if not.","Avoid GGUF-via-diffusers and torchao fp8/int8 loads when ControlNet is part of the workflow."],"exampleFix":"# before: GGUF load + controlnet -> ValueError\nPOST /images/load {\"repo_id\": \"...\", \"gguf_filename\": \"...Q4_K_M.gguf\"}\nengine.generate(prompt=p, controlnet=cn)\n# after: bf16 load\nPOST /images/load {\"repo_id\": \"...\"}  # no gguf_filename, no torchao scheme\nengine.generate(prompt=p, controlnet=cn)","handlingStrategy":"try-catch","validationCode":"def cn_supported(state) -> bool:\n    from core.inference import diffusion_controlnet\n    return diffusion_controlnet.supports_controlnet(\n        engine=\"diffusers\",\n        family=state.family.name,\n        has_controlnet_pipeline=bool(getattr(state.family, \"controlnet_pipeline_class\", None)),\n        model_kind=state.kind,\n        transformer_quant=state.transformer_quant,\n    )","typeGuard":null,"tryCatchPattern":"try:\n    out = engine.generate(prompt=p, controlnet=cn)\nexcept ValueError as e:\n    if \"not supported for this model/quantisation\" in str(e):\n        notify_user(\"Reload the model as bf16 or bnb-4bit to use ControlNet.\")\n    else:\n        raise","preventionTips":["Load bf16 or bnb-4bit builds when ControlNet is part of the plan; avoid GGUF/torchao fp8/int8 for those sessions.","Call supports_controlnet() client-app-side before exposing CN controls for the loaded model."],"tags":["diffusion","controlnet","quantisation","gguf","torchao","validation"],"backgroundTag":null,"analyzedSha":"203007d19051dcd2ae33876786d117c99f6b0368","analyzedAt":"2026-08-15T02:48:39.846Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}