Hugging Face 401/403 on Gated Models: Fix Access and Token Mismatch

Quick fix: check these three things in order:

1. Is the exact Hugging Face account approved for the gated repository?
2. Does hf auth whoami show that same account in the environment doing the download?
3. Is HF_TOKEN overriding the login you think the process is using?

A new token will not fix an account that has not been approved, and a successful browser login will not help a service that is running under another identity or token.

Never paste tokens into support issues, logs, screenshots or Git repositories.

Start by identifying the failed access boundary

Several different problems can look similar:

A single HTTP status is not a universal diagnosis. Different API paths and client libraries can wrap errors differently. Read the full, redacted exception, including any explicit gated-repository message and the requested repository ID.

Step 1: Verify access in your browser

Open the model’s actual Hub page, using its exact owner and repository name:

https://huggingface.co/owner/model

Replace the example path with the real repo ID.

For a gated model, the Hub’s documented access request is made in the browser. Some authors automatically approve requests after you agree to their conditions; others review each request manually. Until the account’s request is approved, installing new Python packages or generating extra access tokens will not solve the missing permission.

The Hub states that gated access is granted to individual users. Membership in an organization, viewing the public model card, or having a technically valid token does not necessarily grant access to the repository’s gated files. Access may also be revoked by the owner. Check the actual request status before further troubleshooting.

Do not try to circumvent the author’s gating or licensing requirements through unauthorized mirrors or another person’s credentials.

Step 2: Check who the command line is logged in as

On the machine running the failed download, check the active account:

hf auth whoami

If no account is recognized, follow the CLI’s supported interactive login:

hf auth login

Then run hf auth whoami again. The account reported by the CLI should be the one approved for the gated repository.

This check must occur in the same environment as the failing process. A model download in a Docker container, job runner, notebook kernel, system service or a different Linux account may not use the same credentials as your ordinary terminal. Authentication that works in your browser or host shell does not prove that another user or process has access.

Step 3: Watch for an old environment token

Hugging Face’s authentication documentation gives environment-provided tokens priority over the token stored on disk. That can make a successful new CLI login appear ineffective: the service is still reading a different token from HF_TOKEN.

Without printing the token, check whether the environment supplies it:

if printenv HF_TOKEN >/dev/null 2>&1; then
  printf 'HF_TOKEN is set\n'
else
  printf 'HF_TOKEN is not set\n'
fi

If the variable is set, inspect your application launcher or approved secret reference instead of dumping environment values. Also inspect a deliberate HF_HOME override, which changes where Hub configuration and cached files live.

Use a read-scoped, least-privilege token when only downloads are required. Keep it in a secure mechanism appropriate for the host or deployment. Do not hardcode tokens into shell history, source files, command examples or build logs.

Step 4: Try downloading a small known file

A multi-gigabyte weight download is not the best first permissions test. Once the account appears approved, request a small file known to exist in that repository, such as its configuration:

hf download owner/model config.json

Replace owner/model. Confirm that config.json exists in the target model first; otherwise a missing-file error can be mistaken for an access failure. The Hub CLI’s download command uses the same underlying file-download mechanisms as the Python Hub library.

For a Python-only environment, a minimal check is:

from huggingface_hub import hf_hub_download

def main():
    repo_id = "owner/model"
    downloaded = hf_hub_download(repo_id=repo_id, filename="config.json")
    print(downloaded)

if __name__ == "__main__":
    main()

This is a complete example once you replace the repository name with one that contains config.json and has been approved for the running identity. It prints a cache path rather than a secret. The Python interface supports explicit tokens, but use an approved environment or secret manager rather than a literal token embedded in source.

If a small known file succeeds, move to the exact failing filename or model snapshot. Investigate revision identifiers, file availability, storage and network transport, rather than repeatedly logging in without evidence that authentication is the remaining issue.

Step 5: Distinguish permission, identity and repository errors

The user is not approved. The model owner has not yet granted access. Wait for approval or follow the published conditions. A new token for the same unapproved user does not change this.

The downloader is a different user. The browser uses one Hugging Face identity while the service or CLI uses another. Verify the effective account in the environment performing the download.

A token override takes precedence. The application reads HF_TOKEN from a secret store or process environment that differs from the token you expected. Correct the secret reference or launcher configuration rather than exposing token values to debug output.

The repository or revision is wrong. Copy the owner/repository name exactly. If you specified a branch, tag or commit, verify it exists. The official Hub download guide documents downloading at an explicit revision.

The failure is no longer about authentication. Once permissions succeed, network interruption, cache corruption, file transfer or unsupported runtime format may produce a different error. Preserve that new error and debug it separately. Reinstalling Transformers or PyTorch is not a targeted fix for an explicit gated-access denial.

A privacy-safe evidence checklist

Before asking for support, collect the following information:

1. The repository ID, and a filename and revision if specified.
2. The exact operation or library method and its version.
3. Whether browser access is approved, pending, or the repository is not gated.
4. Whether hf auth whoami reports the expected user from the same execution environment.
5. Whether HF_TOKEN or a nondefault HF_HOME is configured, without showing its contents.
6. The HTTP status, exception class and a redacted excerpt of the error.

Never include an authorization header, full environment dump, token file or credentials in a public report. If a token has leaked, rotate or revoke it using the provider’s supported controls and update the dependent service.

Practical decision sequence

If the browser request is pending, resolve the gating approval first. If approval is granted but hf auth whoami identifies another account, correct the execution identity. If the correct account is active but a service still fails, check environment-token precedence. Only then test a small known file and examine exact revision, filenames and network behaviour.

This sequence separates access control from model compatibility and avoids destructive, broad changes to a working Python environment.

Primary documentation

• Gated-model access and individual approvals
• Hugging Face Hub authentication quickstart
• Hub file downloads and revisions
• Hub CLI identity and download commands

After the download is fixed, continue with How to Run an LLM Locally and How Much VRAM Do You Need for LLMs?.