unslothai/unsloth · error · HTTPException

Access to '{repo}' is gated or unauthorized. Accept the mode

Error message

Access to '{repo}' is gated or unauthorized. Accept the model's license on its Hugging Face page and add your HF token in Studio settings, then try again.

What it means

HTTP 400 raised by the diffusion-model preflight: for a Hub repo (not local, not .gguf) the route sends a HEAD request to https://huggingface.co/{repo}/resolve/main/model_index.json with the caller's HF token. A 401/403 response means the repo is gated and the token has not accepted its license (or the token lacks access), so training would fail later anyway — the route fails fast with instructions. 404 and network errors are intentionally ignored (not an access problem).

Source

Thrown at studio/backend/routes/training.py:2623

    # clone counts: a directory named exactly like the vendor id is what the loaders and the
    # mirror override both resolve on disk, and it carries one slash and no leading marker, so
    # without the existence test this HEADs the gated repo and 400s a run that never leaves disk.
    if (
        not repo
        or repo.count("/") != 1
        or repo.startswith((".", "/", "~"))
        or repo.endswith(".gguf")
        or _is_local_path(repo)
    ):
        return
    url = f"https://huggingface.co/{repo}/resolve/main/model_index.json"
    headers = {"Authorization": f"Bearer {hf_token}"} if hf_token else {}
    req = urllib.request.Request(url, method = "HEAD", headers = headers)
    try:
        urllib.request.urlopen(req, timeout = 5)
    except urllib.error.HTTPError as e:
        if e.code in (401, 403):
            raise HTTPException(
                status_code = 400,
                detail = (
                    f"Access to '{repo}' is gated or unauthorized. Accept the model's license "
                    f"on its Hugging Face page and add your HF token in Studio settings, then "
                    f"try again."
                ),
            )
        # 404 (e.g. a repo without a root model_index.json) and other codes are not an access problem; let the trainer surface any genuine load error.
    except Exception:  # noqa: BLE001 -- network/DNS hiccup must not block a start
        return


def _resolve_diffusion_data_dir(raw: str) -> Path:
    """Resolve a diffusion-training ``data_dir``. The upload/labeling routes create and
    manage image datasets directly under ``datasets_root()`` and the UI passes the bare
    folder name back as ``data_dir``, but the generic :func:`resolve_dataset_path`
    searches the LLM uploads and recipe dataset roots FIRST -- so an unrelated upload
    file or recipe folder sharing that name would shadow the just-uploaded image

View on GitHub (pinned to 203007d190)

Solutions

1. Open the model's Hugging Face page and accept its license agreement.
2. Add/refresh a valid HF token with access to the repo in Studio settings.
3. Retry the training start; verify quickly with: curl -I -H "Authorization: Bearer $HF_TOKEN" https://huggingface.co/{repo}/resolve/main/model_index.json (expect 200/302, not 401/403).

async function canAccessRepo(repo, token) {
  const res = await fetch(`https://huggingface.co/${repo}/resolve/main/model_index.json`, {
    method: 'HEAD', headers: token ? {Authorization: `Bearer ${token}`} : {},
  })
  return res.status !== 401 && res.status !== 403 // 404 means: not an access problem
}
if (!(await canAccessRepo(modelRepo, hfToken))) throw new Error('Accept the model license on HF and set a valid token first')

try { await startDiffusion(payload) } catch (e) { if (e.status === 400 && /gated or unauthorized/.test(e.detail)) { promptUser('Accept the license on the model page and add an HF token in Settings'); return } throw e }

When it happens

Trigger: POST diffusion training start with model_repo_id pointing at a gated Hub repo (e.g. FLUX dev variants) while hf_token is missing, expired, or belongs to an account that has not accepted the model's license.

Common situations: New users copying a trendy gated model name without a token; tokens revoked/expired; accounts that accepted the license on one account but use another's token.

Understand the failure class

• Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

• '{base_model}' is a gated Hugging Face repo. Accept its lice
• '{repo}' is gated on Hugging Face and this model cannot be d
• Invalid repo_id: {repo_id!r}
• Dataset appears to be empty or could not be streamed
• dataset_name must be a Hugging Face repo id like org/repo

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