Learn AI Create the Future — with Pranay
Main site

Error database

GatedRepoError / 401 Unauthorized: Cannot access gated repo (Hugging Face)

The model is gated — you must accept its license on the model page and authenticate with a token. Request access first, then log in with huggingface-cli.

The message you saw
GatedRepoError / 401 Unauthorized: Cannot access gated repo (Hugging Face)

By Updated

The error

Output
huggingface_hub.errors.GatedRepoError: 403 Client Error. Cannot access gated repo for url https://huggingface.co/meta-llama/Llama-3.1-8B-Instruct/resolve/main/config.json.
Access to model meta-llama/Llama-3.1-8B-Instruct is restricted. You must have access to it and be authenticated to access it. Please log in.

With no token at all, it appears as a plain 401:

Output
OSError: You are trying to access a gated repo. Make sure to have access to it at https://huggingface.co/meta-llama/Llama-3.1-8B-Instruct.
401 Client Error. (Request ID: ...)
Cannot access gated repo for url ...: Invalid credentials in Authorization header

What it means

A gated repo is a model whose owner requires you to accept a license before downloading — Meta's Llama models and Google's Gemma models are the famous examples. Two separate conditions must both hold: your Hugging Face account has been granted access to that specific repo, and the running code authenticates as that account with a token. Missing either one produces these errors.

Why it happens

People do one half and not the other. They accept the license in the browser but the script has no token. Or they set a token but never requested access to this particular model. Two subtler versions: the token belongs to a different account than the one granted access, or the token was created without read permission.

How to fix it

1. Request access on the model page. Open the model on huggingface.co while logged in, and use the access-request form at the top. Some grants are instant; Meta's can take a while — wait for the confirmation email before debugging further.

2. Authenticate the machine.

bash
huggingface-cli login

Paste a token from huggingface.co → Settings → Access Tokens. Create it with at least Read access. For servers and CI, set it as an environment variable instead:

bash
export HF_TOKEN=hf_xxxxxxxxxxxxxxxxxxxx

3. Verify which account the machine is using.

bash
huggingface-cli whoami

If that is not the account that accepted the license, you found the bug.

4. In code, the logged-in token is picked up automatically. Passing it explicitly also works:

python
model = AutoModelForCausalLM.from_pretrained(
    "meta-llama/Llama-3.1-8B-Instruct", token=True
)

5. A 404 RepositoryNotFoundError instead? Check the repo id spelling. Private and nonexistent repos both return 404 — a typo in the org or model name looks identical to a permissions problem.

6. No access and no patience? Use an open alternative. Many gated models have ungated fine-tunes or equivalents (for example Mistral and Qwen families) that need no approval.

How to prevent it

Do the license-plus-login dance once per machine and per account, before the training script runs. In team settings, document which account holds the model grants, and use an organisation token rather than personal ones scattered across servers.