unslothai/unsloth · error · ValueError

ControlNet is not supported for this model/quantisation on t

Error message

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).

What it means

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.

Source

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

                    # strength 0 disables CN: skip the whole path so a no-op never pays the download/VRAM.
                    if cn_strength in (None, 0, 0.0):
                        controlnet = None
                    else:
                        if workflow != "txt2img":
                            raise ValueError(
                                "ControlNet currently combines with plain text-to-image only, not "
                                f"the {workflow} workflow."
                            )
                        if not diffusion_controlnet.supports_controlnet(
                            engine = "diffusers",
                            family = state.family.name,
                            has_controlnet_pipeline = bool(
                                getattr(state.family, "controlnet_pipeline_class", None)
                            ),
                            model_kind = state.kind,
                            transformer_quant = state.transformer_quant,
                        ):
                            raise ValueError(
                                "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)."
                            )
                        # Decode + preprocess the control image FIRST so a bad image 400s before any CN download, at the OUTPUT size.
                        src = decode_b64_image(cn_image_b64, mode = "RGB")
                        control_pil = diffusion_controlnet.preprocess_control(src, cn_type).resize(
                            (width, height), Image.LANCZOS
                        )
                        try:
                            resolved_cn = diffusion_controlnet.resolve_controlnet(
                                cn_id, family = state.family.name
                            )
                        except FileNotFoundError as exc:
                            # An unknown CN id -> 400, not 500 (the route maps ValueError).
                            raise ValueError(str(exc)) from exc
                        pipe = self._controlnet_pipe(state, resolved_cn, cancel)
                        workflow = "controlnet"

View on GitHub (pinned to 203007d190)

Solutions

1. Reload the model in bf16 (full precision load) or bnb-4bit and retry the ControlNet request.
2. 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.
3. Avoid GGUF-via-diffusers and torchao fp8/int8 loads when ControlNet is part of the workflow.

Example fix

# before: GGUF load + controlnet -> ValueError
POST /images/load {"repo_id": "...", "gguf_filename": "...Q4_K_M.gguf"}
engine.generate(prompt=p, controlnet=cn)
# after: bf16 load
POST /images/load {"repo_id": "..."}  # no gguf_filename, no torchao scheme
engine.generate(prompt=p, controlnet=cn)

def cn_supported(state) -> bool:
    from core.inference import diffusion_controlnet
    return diffusion_controlnet.supports_controlnet(
        engine="diffusers",
        family=state.family.name,
        has_controlnet_pipeline=bool(getattr(state.family, "controlnet_pipeline_class", None)),
        model_kind=state.kind,
        transformer_quant=state.transformer_quant,
    )

try:
    out = engine.generate(prompt=p, controlnet=cn)
except ValueError as e:
    if "not supported for this model/quantisation" in str(e):
        notify_user("Reload the model as bf16 or bnb-4bit to use ControlNet.")
    else:
        raise

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• a single-file checkpoint name is required for a '{kind}' loa
• a 'gguf' load requires a .gguf checkpoint name.
• a .gguf checkpoint needs model_kind 'gguf', not 'single_file
• Local model path does not exist: {repo_id}
• '{repo_id}' is a single-file GGUF repo; load it with model_k

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