unslothai/unsloth · error · ValueError

'{family_name}' needs diffusers ({pipeline_class}), which th

Error message

'{family_name}' needs diffusers ({pipeline_class}), which this environment cannot import: {exc}. Install or repair it with: pip install -U diffusers.

What it means

In strict mode (the training path), probing diffusers for the family's pipeline class raised while importing — diffusers is missing entirely, or it is a broken/lazy install whose pipeline submodule import fails (e.g. 'Failed to import diffusers.pipelines...' from unsatisfiable sub-dependencies). Strict refuses here because the trainer's spawn child would fail the same import only after GPU models were already freed. The guard always raises ValueError so routes map it to 400 with the message intact.

Source

Thrown at studio/backend/core/inference/diffusion_families.py:1148

    try:
        import diffusers
        present = hasattr(diffusers, pipeline_class)
        dummy_backends = _dummy_required_backends(getattr(diffusers, pipeline_class, None))
    except Exception as exc:  # noqa: BLE001 -- see below: this check must never raise anything but its own ValueError
        # Not this check's business under the default: it answers "is the installed diffusers new enough for this
        # family", and with nothing importable there is no version to judge. Refusing would also break the native
        # sd.cpp engine, which serves GGUF picks on a CPU or Apple host without diffusers. A pick that really needs
        # it fails later, in the loader. The one thing that must not happen is a raise of the wrong type:
        # ModuleNotFoundError is not the ValueError the routes map to 400, so it escapes /images/download-plan as a
        # bare 500 with the message lost.
        #
        # The attribute probe is inside the try for the same reason. diffusers' top level is a lazy module, so
        # ``hasattr`` is what actually imports the pipeline's submodule, and when that submodule's own dependencies
        # are unsatisfiable it raises RuntimeError ("Failed to import diffusers.pipelines...") -- which hasattr does
        # NOT swallow, since it only absorbs AttributeError. A partially usable diffusers install therefore escaped
        # this guard exactly the way a missing one used to.
        if strict:
            raise ValueError(
                f"'{family_name}' needs diffusers ({pipeline_class}), which this environment "
                f"cannot import: {exc}. Install or repair it with: pip install -U diffusers."
            ) from None
        return

    if present and dummy_backends:
        # A placeholder, not the pipeline. Under the default this is left alone like every other
        # unusable install; strict refuses, because the trainer child imports the same placeholder
        # and its from_pretrained raises only after the GPU residents are gone.
        if not strict:
            return
        raise ValueError(
            f"'{family_name}' needs diffusers ({pipeline_class}), but this diffusers exports it as "
            f"a placeholder, which it does when a backend it requires is unavailable. That class "
            f"requires: {', '.join(dummy_backends)}. Check which of those this environment is "
            f"missing and install it."
        )

View on GitHub (pinned to 203007d190)

Solutions

  1. pip install -U diffusers (as the message says) into the environment the trainer runs in
  2. If it still fails, reinstall cleanly: pip uninstall -y diffusers && pip install -U diffusers, and check the chained exception for the missing sub-dependency
  3. Verify with: python -c "import diffusers; hasattr(diffusers, '<pipeline_class>')" from the same interpreter/venv
  4. Do not attempt training on hosts intentionally running diffusers-free sd.cpp; use a host with diffusers installed

Example fix

# before
# host has no diffusers; training request for Flux2Klein -> ValueError

# after
pip install -U diffusers
python -c "import diffusers; assert hasattr(diffusers, 'Flux2KleenPipeline')"  # adjust class name
Defensive patterns

Strategy: validation

Validate before calling

def diffusers_importable_for(pipeline_class: str) -> bool:
    try:
        import diffusers
        return hasattr(diffusers, pipeline_class)  # probe imports the lazy submodule
    except Exception:
        return False

Try / catch

try:
    validate_family_pipeline(pipeline_class, family_name, strict=True)
except ValueError as e:
    # environment defect: surface the pip guidance to the user, do not start training
    return bad_request(str(e))

Prevention

When it happens

Trigger: Starting training for a diffusers-based family on a host where 'import diffusers' or the hasattr(diffusers, pipeline_class) probe raises: not installed, partially installed, or its dependencies (torch/transformers versions) unsatisfiable. Inference (strict=False) stays silent and only the too-old check applies.

Common situations: CPU or Apple host serving GGUF via sd.cpp with no diffusers installed, then a training request arrives; broken venv after upgrading torch without reinstalling diffusers; Python 3.9 environment holding an old or partial diffusers.

Related errors

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