{"record":{"id":"d2dd4aaf3219eaab","repo":"unslothai/unsloth","slug":"base-model-is-a-gated-hugging-face-repo-accep","errorCode":null,"errorMessage":"'{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.","messagePattern":"'(.+?)' is a gated Hugging Face repo\\. Accept its license on the Hub and add your HF token in Studio settings before training from it\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"studio/backend/core/training/diffusion_dit_trainer.py","lineNumber":1503,"sourceCode":"    ),\n}\n\n\n# 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.\n_GATED_TRAIN_REPOS = frozenset({\"black-forest-labs/flux.1-dev\", \"black-forest-labs/flux.2-dev\"})\n\n\ndef _assert_gated_access(base_model: str, hf_token: Optional[str]) -> None:\n    \"\"\"Raise a clear error before loading a gated base without a token.\"\"\"\n    from core.inference.diffusion_families import _is_local_path\n\n    name = str(base_model or \"\").strip().lower()\n    # A local clone named like the vendor repo is weights on disk, not a Hub fetch: no gate\n    # applies, and refusing it by name alone is what made that documented layout untrainable.\n    if _is_local_path(base_model):\n        return\n    if name in _GATED_TRAIN_REPOS and not (hf_token and str(hf_token).strip()):\n        raise ValueError(\n            f\"'{base_model}' is a gated Hugging Face repo. Accept its license on the Hub \"\n            f\"and add your HF token in Studio settings before training from it.\"\n        )\n\n\ndef _open_resized(path, resolution):\n    \"\"\"Open + EXIF-orient + short-side resize to ``resolution`` (same geometry as the SDXL\n    loader). Returns the resized PIL image and its (rw, rh).\"\"\"\n    from PIL import Image, ImageOps\n\n    img = ImageOps.exif_transpose(Image.open(path)).convert(\"RGB\")\n    w0, h0 = img.size\n    scale = resolution / min(w0, h0)\n    rw, rh = max(resolution, round(w0 * scale)), max(resolution, round(h0 * scale))\n    return img.resize((rw, rh), Image.LANCZOS), rw, rh\n\n\ndef _to_unit_tensor(img):","sourceCodeStart":1485,"sourceCodeEnd":1521,"githubUrl":"https://github.com/unslothai/unsloth/blob/203007d19051dcd2ae33876786d117c99f6b0368/studio/backend/core/training/diffusion_dit_trainer.py#L1485-L1521","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Open the model page on Hugging Face and accept its license agreement for your account.","Add a valid HF token in Studio settings (or pass cfg.hf_token) and restart the run.","Alternatively point base_model at a local clone of the weights on disk — the gate does not apply to local paths."],"exampleFix":"# before\ntrain(cfg)  # cfg.base_model = \"black-forest-labs/FLUX.1-dev\", cfg.hf_token = None\n\n# after\ncfg.hf_token = os.environ[\"HF_TOKEN\"]  # token for an account that accepted the license\ntrain(cfg)","handlingStrategy":"validation","validationCode":"def can_fetch(base_model: str, hf_token: str | None, gated_repos: set[str]) -> bool:\n    name = str(base_model or \"\").strip().lower()\n    if name not in gated_repos:\n        return True\n    return bool(hf_token and str(hf_token).strip())","typeGuard":null,"tryCatchPattern":"try:\n    _assert_gated_access(cfg.base_model, cfg.hf_token)\nexcept ValueError as e:\n    if \"gated\" in str(e):\n        raise SystemExit(\"Accept the license on the Hub, then set cfg.hf_token / HF_TOKEN\")\n    raise","preventionTips":["Configure the HF token in Studio settings once per host, not per run.","Accept gated licenses on the Hub before scheduling training runs.","For air-gapped setups, clone the weights locally — local paths bypass the gate."],"tags":["huggingface","auth","gated-model","training"],"backgroundTag":null,"analyzedSha":"203007d19051dcd2ae33876786d117c99f6b0368","analyzedAt":"2026-08-15T02:48:39.846Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}