Hugging Face "401 Client Error: Repository Not Found" in CI

The Hub returned 401 because the request carried no valid token. For private and gated repos it answers "Repository Not Found" rather than confirming existence, so a missing HF_TOKEN in CI looks like a missing repo.

What this error means

huggingface_hub raises "401 Client Error ... Repository Not Found for url: https://huggingface.co/api/models/<repo>" during a download or hf_hub_download call.

huggingface_hub

huggingface_hub.utils._errors.RepositoryNotFoundError: 401 Client Error.
Repository Not Found for url: https://huggingface.co/api/models/org/private-model/revision/main.
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.

Common causes

No token was provided to the runner

The secret was never exported to the step, so huggingface_hub sends an anonymous request and the Hub answers 401 for the private repo.

The token is expired, revoked, or malformed

A stale or truncated token authenticates as nobody, producing the same 401 even though a value is set.

How to fix it

Provide a valid read token as HF_TOKEN

Create a read access token in your Hub account settings.
Store it as a repository or organization secret.
Export it as HF_TOKEN in the job env so all HF libraries pick it up.

.github/workflows/ci.yml

env:
  HF_TOKEN: ${{ secrets.HF_TOKEN }}

Confirm the token value on the runner

Check that the secret is non-empty in the step (without printing it) and regenerate it if it may be revoked.

Terminal

python -c "import os,sys; sys.exit(0 if os.environ.get('HF_TOKEN') else 'HF_TOKEN is empty')"

How to prevent it

Set HF_TOKEN for every job that touches private or gated repos.
Use read-scoped tokens for pulls and rotate them on a schedule.
Gate downloads behind a check that the token is present.