unslothai/unsloth · error · ValueError

'{repo}' is gated on Hugging Face and this model cannot be d

Error message

'{repo}' is gated on Hugging Face and this model cannot be downloaded without it. Accept its licence at {url}, then add a Hugging Face token that has access in Studio settings and try again.

What it means

Raised from the HF access probe when HfApi().model_info(repo) raises GatedRepoError (or a later metadata HEAD on the probe file does): the base repo requires accepting a licence on Hugging Face, and the request's token either lacks acceptance or was made without one. The probe escapes to a cached snapshot when the model is already fully downloaded, otherwise it fails with this actionable message.

Source

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

                    return True
        except Exception:  # noqa: BLE001 — a cache we cannot read is not an access verdict
            pass
        return False

    def _is_auth_error(exc: Any) -> bool:
        """A 401/403 that hf_raise_for_status did not classify: an expired token 401s "Invalid
        credentials in Authorization header", which _http.py excludes from its RepoNotFound branch
        by name, and a token missing a permission 403s. Both arrive as plain HfHubHTTPError, so
        catching only the classified errors fails open on the very case this probe exists to catch."""
        status = getattr(getattr(exc, "response", None), "status_code", None)
        return status in (401, 403)

    try:
        gated = getattr(HfApi().model_info(repo, token = hf_token), "gated", None)
    except GatedRepoError:  # a gated repo can also withhold its metadata
        if _already_downloaded():
            return other_root_snapshot
        raise ValueError(_repo_access_message(repo, gated = True)) from None
    except RepositoryNotFoundError as exc:
        # 401 and 404 both land here: hf_raise_for_status folds unauthenticated private/gated in
        # with a missing repo because "401 is misleading" (_http.py), so re-read the status. A
        # 401/403 earns the cache escape; a genuine 404, or an error carrying no response, raises.
        if _is_auth_error(exc) and _already_downloaded():
            return other_root_snapshot
        raise ValueError(_repo_access_message(repo, gated = False)) from None
    except HfHubHTTPError as exc:
        if not _is_auth_error(exc):
            return None  # a 5xx or rate limit is not an access verdict
        if _already_downloaded():
            return other_root_snapshot
        raise ValueError(_repo_access_message(repo, gated = False)) from None
    except Exception:  # noqa: BLE001 — offline / transient: the download surfaces any real error
        return None
    # Nothing to carry: model_info answered, so the size estimate lists the base files and the
    # prefetch resolves each through whichever root holds it.
    if not gated or _already_downloaded():

View on GitHub (pinned to 203007d190)

Solutions

Open the repo URL shown in the message in a browser, log in, and accept the licence
Add a Hugging Face token belonging to that account in Studio settings, then retry
If the model was previously downloaded, verify the local snapshot is complete so the probe can use the cache escape

Defensive patterns

Strategy: validation

Validate before calling

def can_access_repo(repo: str, token: str | None) -> bool:
    from huggingface_hub import HfApi, GatedRepoError
    try:
        info = HfApi().model_info(repo, token=token)
        return not getattr(info, "gated", False)
    except GatedRepoError:
        return False
    except Exception:
        return True  # let the download surface the real error

Try / catch

try:
    load_diffusion_model(cfg)
except ValueError as e:
    if "gated on Hugging Face" in str(e):
        show(url_in(e), action="accept licence + set token")

Prevention

Accept gated-model licences in the browser before first load
Keep a valid HF token with the needed access in Studio settings
Fully download gated models once so later loads can use the local snapshot

When it happens

Trigger: Loading a diffusion model whose base repo (often resolved from a card tag) is gated, e.g. FLUX or similar, without having accepted its licence; token present but licence acceptance missing; no token configured at all for a gated repo.

Common situations: First-time use of a newly released gated model; a fresh Studio install with no HF token in settings; token from an account that never accepted the specific model's licence; licence acceptance reset.

Related errors

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