unslothai/unsloth · error · ValueError

Non-GGUF diffusion loads are restricted to unsloth/* repos (

Error message

Non-GGUF diffusion loads are restricted to unsloth/* repos (or a local path); got '{repo_id}'. Pass a gguf_filename to load a GGUF instead.

What it means

Security gate: non-GGUF loads (pipeline and single_file) fetch and deserialize weights via from_pretrained/from_single_file, so they are restricted to the unsloth/* org, a short allowlist of official safetensors base repos (_TRUSTED_NON_GGUF_REPOS, e.g. the SDXL base), and existing local paths. Any other repo id with kind != 'gguf' raises this ValueError naming the offending id and pointing at the GGUF path.

Source

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

        if not family_buildable_here(fam, model_kind = kind):
            assert_pipeline_class_available(fam.pipeline_class, fam.name)
        # Families whose single file IS the whole pipeline have no GGUF path; reject before eviction.
        if kind == "gguf" and fam.single_file_is_pipeline:
            raise ValueError(
                f"'{fam.name}' checkpoints are whole-pipeline single files and have no GGUF "
                f"transformer variant; load the .safetensors pipeline instead of a GGUF."
            )
        # A multi-denoiser family (Ideogram 4) has no transformer-only path; reject before eviction.
        if kind in ("gguf", "single_file") and fam.pipeline_only:
            raise ValueError(
                f"'{fam.name}' loads only as a full diffusers pipeline (it assembles "
                f"multiple transformers), not from a single-file or GGUF checkpoint; "
                f"select the pipeline repo."
            )
        # Non-GGUF loads fetch + deserialise weights, so gate to unsloth/ or a local path.
        if kind != "gguf" and not _is_trusted_diffusion_repo(repo_id):
            raise ValueError(
                f"Non-GGUF diffusion loads are restricted to unsloth/* repos (or a local "
                f"path); got '{repo_id}'. Pass a gguf_filename to load a GGUF instead."
            )
        # The companion base repo also loads via from_pretrained, so it must clear the same trust bar.
        if base_repo and base_repo.strip() and not _is_trusted_diffusion_repo(base_repo):
            raise ValueError(
                f"base_repo is restricted to unsloth/* repos (or a local path); got '{base_repo}'."
            )
        # A local base_repo loads as a full pipeline; reject a non-pipeline one before eviction.
        _assert_local_base_is_pipeline(base_repo)
        # Reject a bad LOCAL pick before the route evicts chat: a path-shaped repo_id must be on disk.
        local_root = Path(repo_id).expanduser()
        # Path-shaped: "."/".." prefix, a backslash (never in "org/name"), or an absolute path.
        path_shaped = (
            repo_id.startswith(("/", "\\", "~", ".")) or "\\" in repo_id or local_root.is_absolute()
        )
        if kind in ("gguf", "single_file"):
            if not gguf_filename:

View on GitHub (pinned to 203007d190)

Solutions

Find the unsloth/* mirror of the model (unsloth republishes the curated safetensors bases) and use that id.
Or pass a gguf_filename to switch the load to the GGUF path, which is open to any repo.
Or download the repo yourself and pass the local directory path - local paths the user points at are trusted.
If the official repo should be trusted, get it added to _TRUSTED_NON_GGUF_REPOS in the backend.

Example fix

# before: third-party org, non-GGUF
manager.validate_load_request(repo_id="stabilityai/stable-diffusion-3.5-large")
# ValueError: Non-GGUF diffusion loads are restricted to unsloth/* ...

# after: curated mirror (or pass gguf_filename, or a local path)
manager.validate_load_request(repo_id="unsloth/stable-diffusion-3.5-large")

Defensive patterns

Strategy: validation

Validate before calling

from pathlib import Path

def non_gguf_load_allowed(repo_id: str) -> bool:
    try:
        if Path(repo_id).expanduser().exists():
            return True
    except OSError:
        pass
    rid = repo_id.strip().lower()
    return rid.startswith("unsloth/")  # or membership in _TRUSTED_NON_GGUF_REPOS

Try / catch

try:
    fam = manager.validate_load_request(repo_id=r, model_kind=k, gguf_filename=f)
except ValueError as e:
    if "restricted to unsloth/*" in str(e):
        suggest_unsloth_mirror_or_gguf(r)
    else:
        raise

Prevention

Prefer unsloth/* ids for pipeline and single-file loads; they are the curated surface by design.
When pasting an HF link, check the org: the original author org is usually not allowlisted for non-GGUF loads.
Local downloads are trusted: clone/snapshot the repo locally and pass the path when you must use a third-party org.
Keep GGUF loads for everything else - the GGUF path stays open to any repo.

When it happens

Trigger: Calling a non-GGUF load with a repo id that is not an existing local path, not under unsloth/, and not in _TRUSTED_NON_GGUF_REPOS - e.g. 'stabilityai/stable-diffusion-3.5-large' or any third-party org - without a gguf_filename.

Common situations: User copies a repo id straight from Hugging Face that belongs to the original author org rather than unsloth's republish; a pipeline preset references a repo that was never allowlisted; attempting a single-file .safetensors load from an arbitrary org.

Related errors

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