Hugging Face 401 and 403 Errors Fixed: Gated Repo Access, the Typo That Returns "Invalid Username or Password", Token Types, hf auth login and HF_TOKEN
A Hugging Face 401 or 403 error almost always means one of three things. You are downloading a gated model without being signed in (401, GatedRepoError, "Cannot access gated repo ... Please log in"). You are signed in but not yet approved for that model (403, "restricted and you are not in the authorized list"). Or your token lacks the permission (403, "Make sure your token has the correct permissions"). The fix is usually three steps: open the model's page and request access, create a read token in your Hugging Face settings, and run hf auth login (or set HF_TOKEN), then download again. Here is the twist that wastes the most time: a typo in the model name also returns 401, with "Repository Not Found" and, underneath, "Invalid username or password.". Hugging Face answers that way on purpose, so that it never reveals whether a private repository exists, and it sends people hunting for a login problem when the real problem is one wrong character. And an invalid token gets exactly the same gated-repo error as no token at all, so "I am logged in" is not proof that your token works. This page decodes every 401, 403, 404 and 429 message from the Hub, the hf CLI and the Python library, and fixes each one.
Ethan wanted to try a gated model on the shop PC, one of the popular ones that needs you to accept a license first. The download failed in a second with "Access denied. Model ... requires approval." He requested access, waited, logged in, and the next attempt failed again, this time with "not found". "So now it doesn't exist?" Jake asked. "It exists," Ethan said, staring at the command. "I typed a 2 where the name has a 3." The error said nothing like that, and that is the trap this page is about.
New to Hugging Face? Hugging Face is the main website for sharing AI models. Most models are public and download without an account, but many popular ones (large language models, image generators, segmentation models) are gated: the author asks you to accept a license and share your contact details before the files unlock. Download tools such as the hf command line, the Python huggingface_hub library, transformers, diffusers, ComfyUI and many local AI apps all fetch from the same Hub, so they all hit the same errors. If you are just starting with local models, our run AI locally series covers the basics.
Every Hugging Face download error, decoded
These are the messages the Hub and its Python library return (huggingface_hub 2.2.0, October 2026), with what each one really means:
| Status and error | Key message | Real cause |
|---|---|---|
401 GatedRepoError | Cannot access gated repo ... You must have access to it and be authenticated to access it. Please log in. | No token sent, or the token is invalid |
403 GatedRepoError | Access to model X is restricted and you are not in the authorized list. Visit ... to ask for access. | Signed in, but no approved access |
403 HfHubHTTPError | 403 Forbidden ... Make sure your token has the correct permissions. | Fine-grained token does not cover this repo or action |
403 DisabledRepoError | Access to this resource is disabled. | The author disabled the repository |
401 RepositoryNotFoundError | Repository Not Found ... Invalid username or password. | Typo in the name, wrong repo type, or a private repo you cannot see |
404 RemoteEntryNotFoundError | Entry Not Found for url ... | The repo exists, but that file does not |
429 HfHubHTTPError | 429 Too Many Requests: you have reached your ... rate limit. Retry after N seconds | Rate limit, often from anonymous requests |
The hf command line shortens these into one-liners. A gated repo without access prints "Error: Access denied. Model 'meta-llama/Llama-3.2-1B' requires approval.", both with no token and with an invalid one. A misspelled repo prints "Error: Model 'meta-llama/Llama-3.2-1B-typo' not found.", followed by a hint that a private repo needs authentication. Add HF_DEBUG=1 to any hf command to see the full traceback with the underlying error class.
Libraries built on huggingface_hub, such as transformers and diffusers, catch these errors and raise their own, but the message still names the gated repository or the missing repository, so the table above tells you which problem you have.
Fix a gated model error, step by step
- Open the model's page on huggingface.co while signed in to the account you will download with. Copy the model name exactly from the page title, which also rules out the typo trap.
- Request access. Gated models show a box asking you to agree to the terms and share your contact details (username and email address) with the authors. Submit it.
- Wait for approval if needed. Many models grant access automatically and instantly. Others use manual approval, and the page shows your request as pending until the authors accept it.
- Create a token in your Hugging Face settings, under Access Tokens. A read token is enough for downloading.
- Log in on the machine: run
hf auth login. It offers a browser sign-in (open the printed URL, enter the short code, approve) or accepts a pasted token. - Confirm with
hf auth whoami. It should print your username, not "Not logged in". - Download again, for example
hf download meta-llama/Llama-3.2-1B config.json, or rerun your app.
The order matters. Access is granted to your account, not to a token, so a token created before or after approval works equally well, as long as it belongs to the approved account. A token from a work account will not open a model you were approved for on your personal account. "So the model knows me, and the token proves it's me," Jake said. "And they both have to be the same me," Ethan said.
Downloading gated models in Python, with proper error handling
In code, pass the token explicitly or rely on your login, and catch the specific errors so your program can say what went wrong instead of dumping a traceback:
import os
from huggingface_hub import snapshot_download, HfApi
from huggingface_hub.errors import GatedRepoError, RepositoryNotFoundError, HfHubHTTPError
REPO = "meta-llama/Llama-3.2-1B"
token = os.environ.get("HF_TOKEN") # or None to use the stored login
try:
HfApi().auth_check(REPO, token=token) # fails fast, before any download
path = snapshot_download(REPO, token=token, allow_patterns=["*.json", "*.safetensors"])
print("downloaded to", path)
except GatedRepoError: # must come BEFORE RepositoryNotFoundError
print(f"{REPO} is gated: request access on its page and log in with the approved account.")
except RepositoryNotFoundError:
print(f"{REPO} not found: check the spelling and repo type (or you lack access to a private repo).")
except HfHubHTTPError as e:
print("Hub error:", e)
Three details make this work. HfApi().auth_check() asks the Hub whether you can access a repo without downloading anything. It succeeds for a public model, raises GatedRepoError for a gated one you cannot open, and raises RepositoryNotFoundError for a misspelled one, so it is the fastest way to test access in a script or a health check. The order of the except blocks matters: GatedRepoError is a subclass of RepositoryNotFoundError (kept that way for backward compatibility), so if you catch RepositoryNotFoundError first, gated errors land there and your "check the spelling" message misleads users. And allow_patterns downloads only the files you need, such as one GGUF quant out of twenty or just the config and weights, which saves time and disk.
How gated access works: automatic, manual, pending and rejected
Model authors choose how access requests are handled, and that decides what you see:
- Automatic approval (the default) grants access as soon as you submit the form. If you still get a 403 right after requesting, your token is probably from a different account, or not being sent at all.
- Manual approval puts you on a pending list until the author accepts. You get the 403 "not in the authorized list" until then. Some authors review once a day, and others take longer.
- Rejected requests show "Your request to access this repo has been rejected by the repo's authors" on the model page, and a rejected user cannot request access again. Contact the authors if you think it was a mistake.
- Reset requests revoke an earlier decision. You lose access, get an email, and have to agree to the terms again.
If a model page shows neither the files nor a request form, refresh it while signed in to the account you download with. A page loaded while signed out, or in another browser profile signed in to a different account, cannot show your own request status or access, and that mix-up is easy to miss.
Gating applies to datasets too, with the same flow and the same errors. If you use an organization account, members request access individually, and an organization can then create a fine-grained token for production use (see tokens).
"Repository Not Found" with a 401: usually a typo
When a repository does not exist, you might expect a 404. Hugging Face returns 401 instead, with "Repository Not Found for url ... Please make sure you specified the correct repo_id and repo_type. If you are trying to access a private or gated repo, make sure you are authenticated ..." and, at the end, the server's message "Invalid username or password.". A plain request for a file in a non-existent repo returns the same 401, with or without a token.
The reason is privacy. If the Hub answered 404 for "does not exist" and 401 for "exists but private", anyone could probe for private repository names. Answering 401 for both hides that information. The cost is confusing messages, so when you see "Repository Not Found", check these in order:
- Spelling and punctuation in both the owner and the model name. A
3.2typed as3-2, or a missing-Instruct, is enough, and dots, dashes and underscores all count. - The repo type. Datasets and Spaces live in separate namespaces, so pass
--repo-type dataseton the CLI orrepo_type="dataset"in Python for datasets. - Whether it moved. Renamed repos usually redirect, but a deleted or private one does not.
- Only then, login. If it is a private repo you should see, check that you are signed in as a member of the owning organization.
Token types: read, write and fine-grained
- Read tokens can read every repository your account can read, public or private, including gated models you were approved for. Use them for downloading.
- Write tokens add the ability to push to repositories you can write to. You only need one for uploading models or editing model cards.
- Fine-grained tokens grant only the specific permissions and repositories you select. They are recommended for production, because a leaked one does limited damage. If a fine-grained token does not include the model you are downloading, you get 403 Forbidden ... Make sure your token has the correct permissions. Edit the token's permissions to add it.
| Token type | Can download gated models you were approved for? | Can upload? | Best for |
|---|---|---|---|
| Read | Yes | No | Laptops, notebooks, anything that only downloads |
| Write | Yes | Yes, to repos you can write to | Training jobs that push models; editing model cards |
| Fine-grained | Only if you include that repo or permission | Only what you grant | Production servers and CI, where a leak should do little harm |
Two organization details catch teams out. A fine-grained token scoped to an organization that requires administrator approval starts in a Pending state and cannot reach the organization's resources until an admin approves it. And for CI pipelines (GitHub Actions, GitLab CI and others), Hugging Face supports Trusted Publishers, which exchange the CI provider's OpenID Connect identity for a short-lived Hub token, so you do not have to store a long-lived token as a secret at all.
Check which account and token are actually in use
"I'm logged in" is the most common wrong assumption, because a broken token behaves exactly like no token. With an invalid token, the gated download failed with the identical 401 "Please log in" message as an anonymous request. Check with:
hf auth whoami # which account the current token belongs to
hf auth list # every token stored on this machine
hf auth switch # pick a different stored token
hf auth token # print the active token (careful: it is a secret)
Without a working token, hf auth whoami prints "Not logged in. Run `hf auth login` first." If it prints a username, make sure it is the account that was approved for the model. If your code runs as a different user (a service, a container, a notebook server), run whoami as that user, because each has its own token store.
HF_TOKEN, where tokens are stored, and Docker
- Stored token:
hf auth loginsaves the token to$HF_HOME/token, which by default is~/.cache/huggingface/token.HF_TOKEN_PATHchanges that location. HF_TOKENenvironment variable: if set, it overrides the stored token. It is the right choice for servers, containers and CI. It is also a common cause of "it works in my terminal but not in my app": a staleHF_TOKENin a service file silently wins over a fresh login.- Docker: pass the token at run time (
docker run -e HF_TOKEN=... image) or mount the token file, and keep it out of the image itself, where anyone who pulls the image could read it. - Implicit use: once you are logged in, the library sends your token with every Hub request, even for public models. Set
HF_HUB_DISABLE_IMPLICIT_TOKEN=1to send it only when needed. - Cache location: downloads go to
$HF_HOME/hub(~/.cache/huggingface/hub). SetHF_HOMEto put the cache on a bigger drive, which large models often need.
Treat a Hugging Face token like a password. A leaked write token lets someone push to your repositories, and a leaked read token exposes your private ones. If one leaks, revoke it in your settings straight away and create a new one. Our guide to the first 30 minutes after a key leak is written for AWS keys, but the same steps apply: revoke, replace, review what it touched.
429 Too Many Requests and the "unauthenticated requests" warning
Anonymous downloads now print a warning: "You are sending unauthenticated requests to the HF Hub. Please set a HF_TOKEN to enable higher rate limits and faster downloads." It is not an error, but it is a hint. Anonymous traffic has lower rate limits, and scripts that list or download many files without a token are the ones that hit 429. The library's 429 message names the limit that ran out and, when the server says so, how long to wait: "429 Too Many Requests: you have reached your ... rate limit. Retry after N seconds".
The fixes are straightforward. Log in, even for public models, to get the higher limits. Download whole repositories with one hf download call instead of thousands of small requests. And when you script many requests, add retries that wait for the time the error gives. If many machines share one network address, such as a CI fleet or a lab, give them a token each, or use a shared cache or mirror so the same files are not fetched again and again.
Offline mode: stop the Hub calls once models are cached
Even when a model is already in your cache, hf_hub_download still makes a quick request to check for a newer version, and that request can fail with the same 401 or 429 errors on a machine with no token or no internet. Set HF_HUB_OFFLINE=1 to skip those checks and load straight from the cache. It also makes startup faster. With offline mode on, calls that truly need the network raise an OfflineModeIsEnabled error instead of hanging. This is the setting to use for air-gapped machines, demos without Wi-Fi, and production servers that should never download a model on their own.
The same errors in local AI apps
- Python scripts and notebooks using transformers or diffusers: run
hf auth loginonce in the same environment, or setHF_TOKENbefore starting the notebook server. Restart the kernel after logging in. - ComfyUI and other node-based tools that download from the Hub usually read the same token file or
HF_TOKEN. Log in as the user the app runs under. - LM Studio and Ollama mostly download public GGUF builds, so gated errors are rare there. If a model only exists as a gated original, look for a community GGUF conversion, which our LM Studio guide and model guides point to.
- Cloud notebooks and servers: store the token in the platform's secrets settings and expose it as
HF_TOKEN, rather than pasting it into a cell.
Our SAM 3 guide walks through one gated model end to end, from the access request to the first run.
Set up a server that downloads gated models safely
- Request access with the right account. For a company, use an organization member's account (or the organization's process) so access does not depend on one person's personal account.
- Create a fine-grained token limited to reading the models you need. If your organization requires administrator approval for tokens, get it approved before the token is needed.
- Store the token as a secret in your platform (a secrets manager, CI secrets, or a Kubernetes secret) and expose it to the app as
HF_TOKEN. Keep it out of code, images and logs. - Point
HF_HOMEat a persistent volume with enough space, so models survive restarts and are not downloaded again. - Download once, then switch on offline mode with
HF_HUB_OFFLINE=1, so the running app never depends on the Hub being reachable or on the token staying valid. - Add an access check to deployment. A one-line
auth_checkin your deploy pipeline catches an expired token or a reset access request before users do. - Rotate the token on a schedule and whenever someone with access leaves. Because the files are cached and the app runs offline, rotation does not interrupt it.
For CI pipelines specifically, consider Trusted Publishers instead of a stored token, so each pipeline run gets a short-lived token through OpenID Connect. That removes the long-lived secret entirely.
Gated datasets work the same way
Datasets can be gated too, with the same access request on the dataset page and the same errors. Two differences matter. Pass --repo-type dataset to hf download (or repo_type="dataset" in Python), because without it the Hub looks for a model with that name and answers "Repository Not Found". And the datasets library's loaders read the same login and HF_TOKEN, so hf auth login once in the same environment is enough. If you are approved for a dataset but get a 403 from a fine-grained token, add the dataset to the token, exactly as with models.
For model authors: gating your own model
If you publish a model and want to know who uses it, or require a license agreement, enable access requests in the repository's settings. You then choose:
- Automatic approval (the default): anyone who agrees and shares their contact details gets access straight away.
- Manual approval: requests wait in a pending list until you accept or reject them, and you set how often you are notified (once a day or in real time).
You can review requests in the UI or through the API with a write token for the repository. The endpoints list pending, accepted and rejected requests (/api/models/{repo_id}/user-access-request/pending and its siblings), and another endpoint changes a user's status to accepted, rejected, pending or reset, optionally with a reason the user sees. Rejected users cannot request again, and a reset makes the user agree to your terms afresh, which is useful when you change the license. Be kind to your users here: a pending queue that nobody checks is the source of many of the 403s people search for.
Revoking and rotating tokens
Tokens do not need to live forever. In your Hugging Face settings you can see every token, its role and when it was last used. You can delete one, or invalidate and refresh it, which issues a new value under the same name. Do this:
- Immediately, if a token was pasted into a public notebook, a chat, a log or a repository.
- When a teammate leaves, for any token they created or knew.
- On a schedule for production tokens, which is easy once your app reads
HF_TOKENfrom a secret store.
After rotating, update the secret everywhere it is used, then run hf auth whoami or an auth_check from each environment. A forgotten copy of the old token is exactly what produces a confusing 401 a week later. Hugging Face also offers a way to report a leaked token for revocation when you are not its owner, for example if you find one in a public repository.
Download only what you need (and check before you download)
Many repositories hold dozens of files, such as several quantizations of one model, so download selectively. hf download takes glob patterns:
# Preview first: which files, and how big
$ hf download HuggingFaceTB/SmolLM2-135M-Instruct --include "*.json" --dry-run
[dry-run] Will download 10 files (out of 10) totalling 3.0M.
# Then fetch one GGUF quant from a big repo
hf download unsloth/MODEL-GGUF --include "*Q4_K_M*" --local-dir models/
# A dataset, a specific branch, and a different token
hf download ORG/DATASET --repo-type dataset --revision v1.0 --token "$HF_TOKEN"
--dry-run is underused. It shows exactly which files match and their total size, and it runs the same access checks as a real download. So it is also a quick way to see whether a gated model's error is fixed, without starting a 20 GB download. --exclude drops files you do not want, such as old *.bin weights next to *.safetensors, and --max-workers sets how many files download in parallel.
Faster downloads, and where they go
Recent versions of huggingface_hub download through Hugging Face's Xet storage system, which keeps its own cache under $HF_HOME/xet next to the model cache at $HF_HOME/hub. Two settings make the biggest difference to speed and reliability. First, log in, because the "unauthenticated requests" warning explicitly mentions higher rate limits and faster downloads for authenticated requests. Second, put HF_HOME on a fast drive with plenty of free space: large models need tens of gigabytes, and a download that fills the disk fails partway, which looks like a network error. Interrupted downloads resume when you rerun the same command, so there is no need to delete a partial download and start over.
Setting the token on Windows
- Interactive login:
hf auth loginworks the same in PowerShell and Command Prompt and stores the token under your user profile's.cache\huggingfacefolder. - For the current PowerShell window:
$env:HF_TOKEN = "hf_...". - Permanently:
setx HF_TOKEN "hf_...", then open a new terminal, becausesetxonly affects windows opened afterwards. - Check:
hf auth whoamiin the same terminal your app or script runs in.
Apps started from the Start menu or as services do not see variables you set in one terminal window. If a desktop app keeps failing after you logged in from a terminal, check whether it runs as a different user, or set HF_TOKEN system-wide.
Why models are gated in the first place
Gating is the author's choice, usually for one of these reasons. Some licenses must be accepted before use, which is common for large language and image models with use restrictions. Some authors want to know who uses the model, by name and email, for research reporting or to contact users about safety updates. And some models are released in stages, with access approved by hand at first. Gating does not mean a model is private or paid. Most gated models are free once you accept, and many approve automatically. It does mean the license applies to you once you accept it, so read it, especially for commercial use. The model card's metadata at the top of its README names the license (a line such as license: apache-2.0), and custom licenses usually link to their full text, which is the part to read before you build anything on the model.
Community re-uploads of gated models
You will often find the same model re-uploaded by others, for example as GGUF conversions for local apps, and some of those copies are not gated. They are convenient, and reputable converters such as the llama.cpp maintainers' ggml-org account and Unsloth are widely used. Two cautions apply. The original license still applies to you whether or not the copy asks you to accept it. And a copy from an unknown account can be modified or mislabeled, so prefer the original repository or a converter with a track record, check the file sizes against the original, and prefer safetensors or GGUF formats over pickle-based .bin files from unknown sources.
Old tutorials: huggingface-cli and use_auth_token
A lot of "login not working" reports come from following instructions written for older versions. Two changes break them:
huggingface-cliis gone. Current versions ofhuggingface_hub(2.2.0 in October 2026) install a single command,hf, and nohuggingface-cli, so old commands fail with "command not found". The replacements arehuggingface-cli login→hf auth login,huggingface-cli whoami→hf auth whoami,huggingface-cli download→hf download, andhuggingface-cli logout→hf auth logout.use_auth_tokenwas removed. Older code passeduse_auth_token=Trueoruse_auth_token="hf_...". Today that raises "TypeError: hf_hub_download() got an unexpected keyword argument 'use_auth_token'". Usetoken=instead, or leave it out to use your login.
If you cannot change a script that depends on the old behavior, pin an older library version for that project in its own virtual environment rather than downgrading your whole system. For anything new, the current commands are simpler, and the browser sign-in in hf auth login means you no longer have to copy and paste tokens on your own machine.
What "401 Client Error: Unauthorized for url" means
Search engines are full of the raw form of these errors, "401 Client Error: Unauthorized for url: https://huggingface.co/...". That line comes from the HTTP layer, and older code or other libraries print it without the explanation that huggingface_hub adds. It tells you only that the Hub refused the request without a valid identity. To find out which of the 401 cases you have, look at the rest of the message, or run the same download with the hf command and HF_DEBUG=1. "Cannot access gated repo" means a gated model and a login problem. "Repository Not Found" plus "Invalid username or password" means a name the Hub will not show you, which is usually a typo. A URL ending in /api/whoami-v2 comes from a token check, so the token itself was missing or rejected, and logging in again is the fix.
Network errors that look like login errors
Some failures are not about access at all, but they show up in the same searches:
- "Connection to huggingface.co timed out", "refused to connect", or SSL errors on huggingface.co:443 mean the request never reached the Hub properly: a firewall, a proxy, a VPN, DNS filtering, or a captive portal on public Wi-Fi. Test in a browser on the same machine, and set the standard
HTTPS_PROXYvariable if your network requires a proxy. - A 403 page that says "The request could not be satisfied" is not the Hub's access control. The Hub is served through Amazon CloudFront, and that is CloudFront's own error page, shown when the request was blocked before it reached Hugging Face, for example from a network address with unusual traffic or through some VPNs. Try another network, switch the VPN off, or wait. Our CloudFront 403 guide explains that page from the website owner's side.
- Server errors (500, 502, 503) are on the Hub's side. Wait and retry. Downloads resume where they stopped.
- Corporate laptops sometimes inspect HTTPS traffic with their own certificate, which breaks certificate checks in Python. Your IT team can provide the certificate bundle to configure, so you do not have to turn security checks off.
A five-minute diagnosis for any Hugging Face download error
- Copy the repo name from the model page and paste it into your command. That rules out the typo that masquerades as a login problem.
- Run a dry run:
hf download REPO --dry-run. If it lists files, access is fine and the problem is in your app's environment. If it fails, read which error it prints. - Check identity:
hf auth whoami, in the same terminal, as the same user, inside the same container as your app. - Check the model page while signed in as that account: does it show the files, a request form, a pending notice or a rejection?
- Check the token type: if it is fine-grained, does it include this repo? Try once with a plain read token to separate permission problems from access problems.
- If nothing above explains it, check the network: try a browser on the same machine, switch off any VPN, and look for timeouts or certificate errors rather than 401 or 403.
Almost every case stops at step 1, 3 or 4. Writing the steps down helps when the error appears on someone else's machine, because they can run the same checks and tell you the output instead of a screenshot of a traceback.
What you share when you request access
Requesting access to a gated model shares your Hugging Face username and email address with the model's authors. That is the trade the authors ask for, and the request form says so. If you would rather not use a personal email, request access from an account with an email address you are comfortable sharing, such as a work account for work projects. Remember that access belongs to that account, so download with its token too. Organization accounts are the tidy option for teams: members request access, and production systems use a fine-grained token tied to the organization rather than to anyone's personal identity.
Cloning with git instead of hf download
Model repositories are git repositories, so you can also git clone https://huggingface.co/OWNER/MODEL, with Git LFS installed for the large files. Gated and private repos then prompt for a username and password. Use your Hugging Face username and your access token as the password, because account passwords are not accepted for git operations. That is why a wrong or missing token in git shows up as the familiar "Invalid username or password". For big models, hf download is usually the better tool anyway. It fetches only the files you ask for, resumes cleanly, and does not keep a second copy of every file in git's own history, which can double the disk space a clone uses.
Common problems and fixes
- Approved, logged in, still 401: the token is invalid or for another account, or a stale
HF_TOKENis overriding your login. Checkhf auth whoamiin the same shell. - Approved, still 403: a fine-grained token missing this repo, or a pending organization token. Use a read token to test, then fix the fine-grained permissions.
- Works on the CLI, fails in the app: the app runs as a different user, or in a container without the token. Pass
HF_TOKENto it. - "Repository Not Found" for a public model: a typo, or a dataset fetched as a model. Copy the name from the page and set the repo type.
- "Entry Not Found": the file name or folder is wrong, or the file is only on a different branch. Check the "Files and versions" tab, and pass
--revisionfor branches. - 429: log in and batch your downloads.
- Request rejected: you cannot request again, so contact the model authors.
Troubleshooting by symptom
Access denied, model requires approval
The hf CLI's message for a gated model you cannot open yet. Request access on the model page, then log in with hf auth login.
Cannot access gated repo, please log in
No valid token reached the Hub. Run hf auth login, or set HF_TOKEN, and check with hf auth whoami.
You are not in the authorized list
You are signed in, but your access is pending or was not granted. Check the model page for your request status.
Invalid username or password when downloading
That is the Hub's answer for a repository it will not show you, usually a typo. Copy the exact name from the model page.
Make sure your token has the correct permissions
A fine-grained token does not cover this model. Add the repo to the token, or test with a read token.
It worked yesterday and fails today
The token was revoked or expired, the request was reset by the authors, or HF_TOKEN changed. Log in again and check the model page.
hf download works but my notebook fails
The notebook kernel started before you logged in, or runs in another environment. Log in from the notebook, or set HF_TOKEN and restart the kernel.
The download stops halfway with a network error
Often the disk filled up. Point HF_HOME at a drive with more space and rerun the command, which resumes the download.
dry-run shows the files, the real download fails
The files need a different token than the one your app uses. Compare hf auth whoami in both places.
Hugging Face 401 and 403 errors: frequently asked questions
Why do I get a 401 error on Hugging Face?
You requested a gated or private repo without a valid token, or the repo name is wrong. Hugging Face also returns 401 for repositories that do not exist.
What does Cannot access gated repo mean?
The model is gated. Request access on its page, then log in with hf auth login or set HF_TOKEN so your requests carry your token.
What does not in the authorized list mean?
You are logged in, but the authors have not approved your access request yet, or rejected it. Check your request status on the model page.
How do I get access to a gated model on Hugging Face?
Sign in, open the model page, agree to the terms and share your contact details, then wait for approval if the model uses manual approval.
How do I log in to Hugging Face from the command line?
Run hf auth login and follow the browser sign-in, or paste a token from your settings. Check with hf auth whoami.
What is a Hugging Face read token?
A token that can read every repo your account can read, including gated models you were approved for. It is enough for downloads.
Why does my fine-grained token get 403?
It does not include the repository or permission you are using. Edit the token to add the model, or use a read token.
Why does Hugging Face say Repository Not Found with a 401?
It hides whether private repos exist, so a typo and a private repo both return 401. Check the spelling and repo type first.
Where is the Hugging Face token stored?
In $HF_HOME/token, which is ~/.cache/huggingface/token by default. The HF_TOKEN environment variable overrides it.
How do I use a Hugging Face token in Docker?
Pass it at run time with -e HF_TOKEN=... or mount the token file. Keep it out of the image.
What does You are sending unauthenticated requests mean?
A warning that you are not logged in. Anonymous requests get lower rate limits, so log in to avoid 429 errors.
How do I fix 429 Too Many Requests on Hugging Face?
Log in for higher limits, batch downloads into fewer requests, and wait for the retry time the error gives.
How do I use cached Hugging Face models offline?
Set HF_HUB_OFFLINE=1. The library then loads from the cache without contacting the Hub.
Does access to a gated model belong to my token or my account?
Your account. Any valid token of the approved account works, and a token from another account does not.
Can I request access again after rejection?
No. A rejected user cannot request access again, so contact the model authors directly.
What does Entry Not Found mean on Hugging Face?
The repository exists, but the file path you asked for does not. Check the file name, folder and branch.
The model is now in the shop PC's cache, and Ethan set HF_HUB_OFFLINE=1 for the app that uses it, so it never phones home again. Jake asked whether he could have guessed the typo from the error. "Not from that error," Ethan said. "It said 'invalid username or password'. The only clue was that my password was fine."
Ethan wrote the six diagnosis steps on a sticky note and put it on the shop PC's monitor, next to the quant rule from last month. The next time a download failed, Jake ran through the list himself, got as far as step 1, and found a missing "-Instruct" in the name. He fixed it before Ethan had finished his coffee, and he has been quietly proud of it ever since.
📌 If you keep one line from this page
401 means no valid token or a wrong name (check spelling first), 403 means signed in but not approved or a token without permission; request access on the model page, use a read token, log in with hf auth login and confirm with hf auth whoami.
huggingface_hub 2.2.0 · hf CLI · tokens in ~/.cache/huggingface/token · October 2026.
Revision note. Written October 22, 2026, with huggingface_hub 2.2.0 and the Hugging Face Hub documentation of that date, with error messages exactly as the library and CLI print them. "Measure twice, cut once," the proverb says, and with model names, read twice and download once.