unslothai/unsloth · error · ValueError

MiniMax-H3 needs the Diffusers revision bundled with this St

Error message

MiniMax-H3 needs the Diffusers revision bundled with this Studio version. Reinstall Studio dependencies and retry.

What it means

Raised for modular-workflow families (MiniMax-H3) when the installed diffusers package does not expose fam.transformer_class. The Modular Diffusers path constructs the denoiser from classes in diffusers, so a too-old diffusers cannot serve the load; the check is done before the load rather than deep inside it, and the fix is to install the diffusers revision bundled with this Studio version.

Source

Thrown at studio/backend/core/inference/video.py:1178

        from .video_minimax_h3 import is_h3_native, validate_h3_transformer_filename

        if is_h3_native(fam, kind):
            validate_h3_transformer_filename(gguf_filename or "")
            # The GGUF filename and explicit task must name the same partition.
            picked = h3_transformer_task(gguf_filename or "")
            if h3_task and h3_task != picked:
                raise ValueError(
                    f"'{Path(gguf_filename or '').name}' is the {picked} partition, but the "
                    f"load asked for {h3_task}. Pick the matching checkpoint."
                )
        else:
            # Refuse a too-old diffusers here rather than deep in the load.
            from .diffusion_families import assert_pipeline_class_available
            assert_pipeline_class_available(fam.pipeline_class, fam.name)
            if fam.modular_workflow:
                import diffusers
                if not hasattr(diffusers, fam.transformer_class):
                    raise ValueError(
                        "MiniMax-H3 needs the Diffusers revision bundled with this Studio "
                        "version. Reinstall Studio dependencies and retry."
                    )
        if kind != "gguf" and not _is_trusted_video_repo(repo_id):
            raise ValueError(
                f"Non-GGUF video loads are limited to unsloth/* repos, the official "
                f"family base repos, and local paths; '{repo_id}' is neither."
            )
        # Companions load with from_pretrained, so a base repo is held to the non-GGUF bar: a GGUF pick must not smuggle in a remote base.
        if base_repo and (base_repo or "").strip() and not _is_trusted_video_repo(base_repo):
            raise ValueError(
                f"base_repo is limited to unsloth/* repos, the official family base "
                f"repos, and local paths; '{base_repo}' is neither."
            )
        # A local base_repo loads as a full pipeline (needs model_index.json); reject a non-pipeline one here, before the load.
        from core.inference.diffusion import _assert_local_base_is_pipeline

        _assert_local_base_is_pipeline(base_repo)

View on GitHub (pinned to 203007d190)

Solutions

  1. Reinstall Studio dependencies so diffusers matches the bundled revision (pip install -r requirements / Studio's setup command).
  2. In a shared env, install Studio in its own venv so other packages cannot move diffusers.
  3. Verify with: python -c "import diffusers; print(hasattr(diffusers, '<transformer_class>'))" — it must print True before retrying.
  4. If pinning manually, take the exact diffusers version from Studio's lockfile.

Example fix

# before: stale diffusers in env
pip install diffusers  # latest, lacks the H3 transformer class

# after
pip install -r studio/backend/requirements.txt  # bundled revision
python -c "import diffusers; assert hasattr(diffusers, 'MiniMaxH3Transformer3DModel')"
Defensive patterns

Strategy: validation

Validate before calling

import diffusers

if not hasattr(diffusers, fam.transformer_class):
    raise SystemExit('Reinstall Studio dependencies: bundled diffusers revision required')

Try / catch

try:
    load(fam, ...)
except ValueError as e:
    if 'Diffusers revision' in str(e):
        subprocess.run([sys.executable, '-m', 'pip', 'install', '-r', REQUIREMENTS])
    else:
        raise

Prevention

When it happens

Trigger: Loading a MiniMax-H3 (or other modular_workflow family) with model_kind != 'gguf' when hasattr(diffusers, fam.transformer_class) is False — typically a system/site-packages diffusers older or newer than the pinned one, or a venv built without the Studio requirements.

Common situations: Upgrading Studio without reinstalling dependencies; another package downgraded/upgraded diffusers in the shared environment; running inside a container whose image cached an old diffusers; using a system Python instead of the bundled venv.

Related errors

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