unslothai/unsloth · error · ValueError

'{base_model}' is a gated Hugging Face repo. Accept its lice

Error message

'{base_model}' is a gated Hugging Face repo. Accept its license on the Hub and add your HF token in Studio settings before training from it.

What it means

Raised by _assert_gated_access() before a gated Hugging Face base model is fetched without credentials. The repo id matches _GATED_TRAIN_REPOS and no non-empty hf_token was supplied. Local paths are exempt: a local clone named like the vendor repo is weights on disk and no Hub gate applies, so the check keys on _is_local_path() first.

Source

Thrown at studio/backend/core/training/diffusion_dit_trainer.py:1503

    ),
}


# HF repos gating access behind a license acceptance: training needs a token whose account accepted it. Checked by name (no network) so a missing token fails fast with an actionable message.
_GATED_TRAIN_REPOS = frozenset({"black-forest-labs/flux.1-dev", "black-forest-labs/flux.2-dev"})


def _assert_gated_access(base_model: str, hf_token: Optional[str]) -> None:
    """Raise a clear error before loading a gated base without a token."""
    from core.inference.diffusion_families import _is_local_path

    name = str(base_model or "").strip().lower()
    # A local clone named like the vendor repo is weights on disk, not a Hub fetch: no gate
    # applies, and refusing it by name alone is what made that documented layout untrainable.
    if _is_local_path(base_model):
        return
    if name in _GATED_TRAIN_REPOS and not (hf_token and str(hf_token).strip()):
        raise ValueError(
            f"'{base_model}' is a gated Hugging Face repo. Accept its license on the Hub "
            f"and add your HF token in Studio settings before training from it."
        )


def _open_resized(path, resolution):
    """Open + EXIF-orient + short-side resize to ``resolution`` (same geometry as the SDXL
    loader). Returns the resized PIL image and its (rw, rh)."""
    from PIL import Image, ImageOps

    img = ImageOps.exif_transpose(Image.open(path)).convert("RGB")
    w0, h0 = img.size
    scale = resolution / min(w0, h0)
    rw, rh = max(resolution, round(w0 * scale)), max(resolution, round(h0 * scale))
    return img.resize((rw, rh), Image.LANCZOS), rw, rh


def _to_unit_tensor(img):

View on GitHub (pinned to 203007d190)

Solutions

1. Open the model page on Hugging Face and accept its license agreement for your account.
2. Add a valid HF token in Studio settings (or pass cfg.hf_token) and restart the run.
3. Alternatively point base_model at a local clone of the weights on disk — the gate does not apply to local paths.

Example fix

# before
train(cfg)  # cfg.base_model = "black-forest-labs/FLUX.1-dev", cfg.hf_token = None

# after
cfg.hf_token = os.environ["HF_TOKEN"]  # token for an account that accepted the license
train(cfg)

def can_fetch(base_model: str, hf_token: str | None, gated_repos: set[str]) -> bool:
    name = str(base_model or "").strip().lower()
    if name not in gated_repos:
        return True
    return bool(hf_token and str(hf_token).strip())

try:
    _assert_gated_access(cfg.base_model, cfg.hf_token)
except ValueError as e:
    if "gated" in str(e):
        raise SystemExit("Accept the license on the Hub, then set cfg.hf_token / HF_TOKEN")
    raise

When it happens

Trigger: Training from a gated repo (e.g. a license-gated FLUX/Qwen base) with hf_token None, empty, or whitespace-only; passing a Hub repo id while the token was never configured in Studio settings; a config that normalization did not redirect to an ungated mirror.

Common situations: First run after downloading a model page without clicking through its license agreement; tokens cleared from settings; a teammate's config shared without their HF token; CI environments with no stored token.

Related errors

• Access to '{repo}' is gated or unauthorized. Accept the mode
• '{repo}' is gated on Hugging Face and this model cannot be d
• hf_dataset is too long (max 256 chars)
• hf_dataset contains invalid characters or path segments
• subset is too long (max {MAX_HF_DATASET_OPTION_LENGTH} chars

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