unslothai/unsloth · error · ValueError

base_repo is restricted to unsloth/* repos (or a local path)

Error message

base_repo is restricted to unsloth/* repos (or a local path); got '{base_repo}'.

What it means

The same trust bar as the main repo, applied to the companion base_repo: a base fed to from_pretrained(base) also fetches and deserialises third-party weights, so it must be unsloth/*, in the trusted allowlist, or an existing local path. Raised pre-eviction, alongside _assert_local_base_is_pipeline which then checks the local base actually is a pipeline directory.

Source

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

                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:
                raise ValueError(f"a single-file checkpoint name is required for a '{kind}' load.")
            # Fail a kind/extension mismatch before the handoff: gguf needs .gguf, single_file must not.
            is_gguf_name = gguf_filename.lower().endswith(".gguf")
            if kind == "gguf" and not is_gguf_name:
                raise ValueError("a 'gguf' load requires a .gguf checkpoint name.")
            if kind == "single_file" and is_gguf_name:

View on GitHub (pinned to 203007d190)

Solutions

1. Use the unsloth/* mirror id for the base repo.
2. Or download the base pipeline locally and pass its directory path as base_repo.
3. Verify the local base directory contains model_index.json, else the follow-up _assert_local_base_is_pipeline check will reject it.
4. Drop base_repo if the family's built-in default base (fam.base_repo) is sufficient.

Example fix

# before
manager.validate_load_request(repo_id="org/model", gguf_filename="m-Q4.gguf",
                              base_repo="black-forest-labs/FLUX.1-dev")

# after: trusted mirror or local pipeline dir
manager.validate_load_request(repo_id="org/model", gguf_filename="m-Q4.gguf",
                              base_repo="unsloth/FLUX.1-dev")

def base_repo_allowed(base_repo: str | None) -> bool:
    if not base_repo or not base_repo.strip():
        return True
    # same trust bar as the primary repo: local path, unsloth/*, or allowlist
    return non_gguf_load_allowed(base_repo.strip())

try:
    fam = manager.validate_load_request(repo_id=r, gguf_filename=f, base_repo=b)
except ValueError as e:
    if "base_repo is restricted" in str(e):
        retry_with_unsloth_base(r, f)
    else:
        raise

When it happens

Trigger: Passing base_repo='someorg/some-base' (not unsloth/*, not allowlisted, not an existing local path) together with a single-file/GGUF load that needs the companion pipeline base.

Common situations: User points base_repo at the original author's base repo instead of the unsloth mirror; base copied from an old config or tutorial predating the trust gate; typo in the base org name.

Related errors

• Non-GGUF diffusion loads are restricted to unsloth/* repos (
• {_cn_fs.reason}
• base_repo is limited to unsloth/* repos, the official family
• Model path is outside Unsloth storage
• VirusTotal request failed after {max_attempts} attempt(s): {

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