Why HuggingFace gives you a 401 or 403 on a gated repo, and how to actually fix it
OSError: You are trying to access a gated repo. Make sure to have access to it at https://huggingface.co/meta-llama/Llama-3.3-70B-Instruct
Also appears as
- requests.exceptions.HTTPError: 401 Client Error: Unauthorized for url: https://huggingface.co/api/models/...
- huggingface_hub.utils._errors.GatedRepoError: Access to model ... is restricted
- 403 Forbidden: Cannot access gated repo for url ...
Short answer
A 401 or 403 on a gated HuggingFace repo means the request reached the Hub but was rejected for authorization, not because the model does not exist. The three real causes are: you have not accepted the model's license on the web page with the account tied to your token, the token exists but was created without read access to gated repos, or the token is valid but was never actually passed to the download call (no HF_TOKEN in the environment, no login run). Fix by accepting the license, generating a token with the right scope, and exporting it where the client library will find it.
Affects: Any gated or license-gated repo on huggingface.co (Llama, Gemma, some Mistral variants), transformers/huggingface_hub of any recent version
Fastest path to a working download
- 1Open the model page on huggingface.co while logged in and click Agree/Accept to accept the license (this is per-account, not automatic).
- 2Create a new access token at huggingface.co/settings/tokens with type Read (or Fine-grained with explicit access to the gated repo).
- 3Export it in the shell you are running from: export HF_TOKEN=hf_xxxxxxxx (or run huggingface-cli login and paste it).
- 4Confirm the CLI sees it: huggingface-cli whoami should print your username, not an error.
- 5Retry the download or from_pretrained call. If it still fails, check the token belongs to the same account that accepted the license (common with org accounts).
How to confirm this is your problem
- Download or from_pretrained call fails immediately with a 401 or 403 before any bytes are transferred
- The same script works for ungated models like a small Qwen or Mistral checkpoint but fails specifically on Llama or Gemma family repos
- huggingface-cli whoami works, but the specific repo still fails
- Error message explicitly says 'gated repo' or 'restricted' rather than 'repository not found'
Root causes and fixes
License not accepted on the HuggingFace website for this account
Gated repos require a per-account, per-model acceptance click on the web UI (sometimes with a form for organizations like Meta). Creating a token does not grant access by itself; the account itself must be separately approved or self-approved for that repo. A perfectly valid token from an account that never clicked Agree will always be rejected.
Fix: Log into huggingface.co with the exact account whose token you are using, open the model page, and accept the license terms. Some repos (certain Llama releases) additionally gate through a Meta approval form that can take minutes to hours to clear.
huggingface-cli whoami
Token has no read scope for gated content, or is a write-only/fine-grained token missing repo access
Fine-grained tokens created for a specific purpose (e.g. only inference API) do not automatically include 'Read access to contents of all public gated repos you can access'. Without that permission box checked, the token authenticates you but the Hub still refuses the specific gated download.
Fix: Regenerate the token as a classic Read token, or edit the fine-grained token to explicitly enable the gated-repo read permission, then re-export it.
huggingface-cli logout huggingface-cli login
Token never reached the process: not exported, wrong shell, or overwritten by CI secrets
huggingface_hub reads HF_TOKEN (or the legacy HUGGING_FACE_HUB_TOKEN) from the environment or from ~/.cache/huggingface/token written by huggingface-cli login. If you exported the token in one terminal and ran the job in another (a different shell, a systemd service, a Docker container without --env), the library falls back to anonymous access and the gated call fails.
Fix: Explicitly pass the token to the call (token="hf_xxx" in from_pretrained, or HF_TOKEN as a Docker/Kubernetes secret env var) instead of relying on ambient shell state, especially in containers and CI.
python -c "import os; print('HF_TOKEN' in os.environ)"
docker run -e HF_TOKEN=$HF_TOKEN ...Organization SSO or org-level gating requires membership approval separate from personal account access
Some enterprise or org-hosted repos require the requesting account to be an approved member of the organization on the Hub, in addition to accepting any license. A personal account that can browse the org's public page may still be rejected on gated assets until an org admin approves membership or grants the token an org-scoped permission.
Fix: Check the organization's member list and pending-request queue on huggingface.co, have an org admin approve access, then regenerate a token under that verified membership.
Cached negative auth state or stale token in huggingface_hub's local cache
huggingface_hub caches some auth and repo metadata locally. After fixing license acceptance or token scope, a stale cached 401 response or an old token stored in ~/.cache/huggingface/token can keep failing until the cache is cleared and the client re-authenticates.
Fix: Delete the cached token and any partial repo metadata cache, then log in again fresh.
rm ~/.cache/huggingface/token huggingface-cli login
Diagnostic commands
Confirm identity
huggingface-cli whoami
If this errors out, no token is configured at all, fix that first. If it prints a username, the token is valid for identity but may still lack gated-repo scope.
Test raw API access to the specific repo
curl -s -H "Authorization: Bearer $HF_TOKEN" https://huggingface.co/api/models/meta-llama/Llama-3.3-70B-Instruct
A JSON response with model metadata means access is granted. A 401 means the token itself is invalid or missing. A 403 with 'gated' in the body confirms license or membership is the blocker, not the token format.
Check where the environment actually runs
env | grep -i hf_token
If empty inside the container or job that fails, the token exists in your interactive shell but was never passed into the execution environment, explaining why it works manually but not in a script or pipeline.
Stopping it from happening again
- Standardize on one org-approved service account token stored as a secret (Kubernetes Secret, Vault, CI secret) rather than personal tokens scattered across engineers' shells.
- For air-gapped or regulated environments, mirror approved gated models into an internal artifact store after one-time authenticated download, so production nodes never need live HuggingFace credentials.
- Document which accounts have accepted which model licenses so a departing employee's token revocation does not silently break a production pipeline.
- Add a pre-flight check in deployment scripts that calls huggingface-cli whoami and a HEAD request to the target repo before starting a long download.
When this becomes an architecture problem
If this is blocking a regulated or air-gapped environment where individual engineers cannot hold live HuggingFace credentials at all, the fix is not a better token, it is an internal model registry: download once through an approved, audited path, verify the artifact, and serve every other environment from your own storage. That is an architecture decision, not a config fix.
Frequently asked questions
I accepted the license, why is it still failing?
License acceptance can take a few minutes to propagate on HuggingFace's side, and for some Meta-gated models there is a second approval step through a separate form that is not instant. Also double check you accepted it with the same account whose token you are using; it is easy to have two browser sessions logged into different accounts.
Does passing use_auth_token still work or do I need token now?
Recent huggingface_hub and transformers versions renamed the parameter to token; use_auth_token is deprecated and may emit a warning or be removed depending on version. Passing token="hf_xxx" explicitly is the more future-proof approach and also avoids ambient environment variable confusion.
Can I download a gated model once and reuse it without a token everywhere else?
Yes, and for air-gapped or regulated deployments this is the recommended pattern: authenticate once from an approved workstation, download the full snapshot, verify its integrity, then copy that local directory to production and load with a local path plus HF_HUB_OFFLINE=1 so no further network or token access is needed.
My token works in Python but not in huggingface-cli download, why?
Check that HF_TOKEN is exported in the exact shell invoking the CLI, not just set inside a Python script via login(token=...) which only affects that Python process's session. Environment variables and huggingface-cli login's saved token file are separate from a token passed programmatically inside one script.
Size it properly next time
Free calculators that prevent this class of failure before you provision hardware.
Air-Gapped LLM Deployment Checklist
A practical control checklist for deploying and maintaining large language models in a fully air-gapped environment, from initial staging through ongoing patching and drift detection.
Free ToolOn-Prem AI Deployment Checklist
A 30-point pre-deployment checklist covering use cases, hardware, security, model operations, and rollout for self-hosted enterprise LLMs.
Free ToolOpen-Weight Model Selector
A 10-question assessment that matches your hardware budget, workload complexity, and operational maturity to the right open-weight model size class.
Related problems
safetensors header too large or invalid header error loading model weights
A safetensors HeaderTooLarge or InvalidHeaderDeserialization error means the file's first bytes are not the expected binary length-prefixed JSON header, almost always because the file on disk is not the actual model weights but a truncated partial download or a small Git LFS pointer text file that was never smudged into the real binary. The fix is to verify the file size matches what the Hub reports and re-download it properly, either with huggingface_hub or with git lfs pull, not to try to repair the file in place.
Model revision or commit not found when pinning a specific version
A revision not found error means the exact commit hash, branch name, or tag you specified does not exist in that repository, most often because it was copied from a different repo, mistyped, or refers to a commit that was later force-pushed away or a tag that was deleted or renamed by the repo maintainer. Fix it by listing the repo's actual available revisions and re-pinning to a real, current one, and build your own immutable mirror if you need guarantees beyond what the source repo's maintainers commit to preserving.
Model loading fails offline or in an air-gapped environment despite having local files
Passing a local path to from_pretrained does not guarantee an offline load, because transformers and related libraries (tokenizers, some model configs, auto-mapping code) can still issue background network calls to check for updates, fetch a referenced remote component, or resolve auto_map entries that point back at the original HuggingFace repo. The fix is to set HF_HUB_OFFLINE=1 and TRANSFORMERS_OFFLINE=1 explicitly, use a complete local snapshot directory (not just the weights file), and verify no config field still references a remote repo ID.
Corrupted model checkpoint fails to load or loads with garbage weights
A corrupted checkpoint means the bytes on disk do not match the original artifact the model author published, whether from an interrupted download, a bad copy between systems, disk-level bit rot, or a failed write during a save operation. There is no reliable way to repair a corrupted deep learning checkpoint; the fix is always to verify the file against a known-good hash or size and re-obtain a clean copy, then build a verification step into your pipeline so the same failure does not silently recur.
GuideSecuring Model Weights in the Enterprise
Secure model weights end to end: custody controls, encryption at rest, access policies, and exfiltration prevention for regulated AI deployments.
GuideAir-Gapped LLM Deployment Patterns That Actually Work
Air-gapped LLM deployment patterns that work: offline model transfer, update workflows, monitoring without telemetry, and CMMC-ready architectures.
GuideOn-Prem LLM Deployment Architecture: Reference Guide
Reference architecture for on-prem LLM deployment: inference servers, GPU sizing, RAG pipelines, and security zones for regulated manufacturers.
Still stuck, or tired of fighting your own infrastructure?
Netray deploys and operates on-prem AI for regulated manufacturers and defense suppliers. We have debugged this stack in production, on air-gapped networks, at scale.