Why a pinned model revision is not found, and how to fix version pinning correctly
huggingface_hub.utils._errors.RevisionNotFoundError: 404 Client Error. Revision Not Found for url
Also appears as
- OSError: revision=... is not a valid git identifier (branch name, tag name or commit id)
- EntryNotFoundError: <file> does not exist on the Hub for revision ...
- Loading works with revision="main" but fails with a pinned commit hash
Short answer
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.
Affects: Any pipeline pinning a specific revision, tag, or commit hash for reproducibility, huggingface_hub of any recent version
Fix it in a few minutes
- 1List the actual branches and tags available on the repo using the Hub API or website to find a valid revision string.
- 2Double check the commit hash was copied from the correct repo; a hash copied from a similar or sibling model repo will not exist in this one.
- 3If pinning main worked before but a specific commit now fails, the repo may have been rebased, force-pushed, or had that commit garbage-collected; choose a current commit instead.
- 4Re-pin to the current head of main (or a currently existing tag) if reproducibility of that exact prior commit is no longer possible, and immediately mirror it internally if you need a durable pin.
- 5For any revision you intend to rely on long-term, download and store your own copy rather than depending on the upstream repo preserving that exact commit indefinitely.
How to confirm this is your problem
- Error explicitly names the revision string you passed and states it was not found
- The same code with revision="main" (or no revision specified) works fine, only the pinned commit or tag fails
- A revision that worked previously in the same script starts failing after some time with no code change
- The revision string looks correct at a glance but was copied from documentation or a different model's example
Root causes and fixes
Commit hash, branch, or tag was copied from the wrong repo or a similar-looking model name
It is easy to copy an example command from documentation, a blog post, or a sibling model's page and forget to update the revision string to match the actual repo you are loading from. Since revisions are specific to a single repository's git history, a perfectly valid-looking commit hash from a different repo will simply not exist in the one you are actually querying.
Fix: Go to the exact repo on huggingface.co, check the Files and versions tab or the commit history, and copy the revision string directly from there rather than from an external example.
python -c "from huggingface_hub import HfApi; print(HfApi().list_repo_refs('org/model'))"The upstream repo was force-pushed, rebased, or had history rewritten, removing the specific commit you pinned
HuggingFace repos are git repositories, and maintainers occasionally rewrite history (squashing commits, removing accidentally-committed large files, restructuring a repo) which can make a previously valid commit hash unreachable even though the repo itself still exists and works fine at its current head. This is a real risk of pinning to someone else's mutable repository rather than to your own controlled copy.
Fix: Re-pin to a currently valid revision, and if you need long-term reproducibility guarantees, download and store the artifacts yourself in your own internal registry rather than depending on the upstream repo's git history remaining stable indefinitely.
python -c "from huggingface_hub import HfApi; print(HfApi().model_info('org/model').sha)"A specific file exists on one revision but was renamed, moved, or removed by a later commit that you are requesting from a different revision
Revision pinning applies per-file-request as well as per-repo-snapshot; if your code requests a specific filename from a specific revision and that file was renamed or reorganized between revisions (a common event when a repo migrates to a new config schema or adds quantized variants), you get an entry-not-found error even though the revision itself is valid.
Fix: Check the repo's file listing at that exact revision (not just at main) to confirm the specific filename you are requesting actually exists there, and update your code's expected filename if the repo's structure changed.
python -c "from huggingface_hub import list_repo_files; print(list_repo_files('org/model', revision='<hash>'))"Typo or accidental whitespace/quote character in the revision string
A revision string with a trailing space, an accidentally included quote character from copy-pasting out of a terminal or markdown document, or a truncated hash (missing characters) will not match any real revision, producing this same not-found error despite looking correct on casual visual inspection.
Fix: Print the exact revision string your code is using and inspect it character by character, or re-type it manually rather than copy-pasting from a source that might have introduced invisible characters.
python -c "print(repr(revision_var))"
Diagnostic commands
List all valid branches and tags for the repo
python -c "from huggingface_hub import HfApi; refs=HfApi().list_repo_refs('org/model'); print([b.name for b in refs.branches], [t.name for t in refs.tags])"Compare your pinned revision string against this actual list. If it is not present, either the revision was deleted/rewritten or you have the wrong value entirely.
Check the repo's current head commit
python -c "from huggingface_hub import HfApi; print(HfApi().model_info('org/model').sha)"This is always a valid, current revision to fall back to if your specifically pinned commit is no longer reachable.
Verify file existence at a specific revision before requesting it
python -c "from huggingface_hub import list_repo_files; print(list_repo_files('org/model', revision='<hash>'))"Confirms whether the specific file your code expects (a particular config or weight filename) actually exists at that exact revision, distinguishing a missing-revision problem from a missing-file-at-a-valid-revision problem.
Stopping it from happening again
- When pinning a revision for reproducibility, download and store a copy of that exact snapshot in your own internal registry immediately, rather than relying on the upstream repo preserving that commit indefinitely.
- Record the full commit hash (not an abbreviated form) and the date you verified it, so you have an audit trail if the upstream repo later changes.
- Re-verify pinned revisions periodically as part of routine maintenance, especially before a scheduled deployment, rather than discovering a broken pin during an incident.
- For regulated environments requiring strict reproducibility, treat the upstream HuggingFace repo as a one-time source and your own internal artifact store as the actual system of record going forward.
When this becomes an architecture problem
If reproducibility of an exact model version is a compliance or audit requirement, relying on an external, mutable git repository's revision history as your only source of truth is not sufficient long-term. The correct architecture is your own internal, immutable artifact registry that captures the exact bytes once, verified, under your own retention and access control policy.
Frequently asked questions
Can a HuggingFace repo maintainer delete a commit I have pinned in production?
Yes, HuggingFace repos are git repositories and maintainers can force-push, rebase, or otherwise rewrite history, which can make a previously valid commit hash unreachable. This is exactly why production systems needing strict reproducibility should mirror the artifact internally rather than depending on the upstream commit remaining available indefinitely.
Is pinning a branch name like main as reliable as pinning a commit hash?
No, main is a moving pointer that changes every time the maintainer pushes new commits, so it gives you the latest version at request time, not a stable, reproducible version. For genuine reproducibility, pin an exact commit hash, and ideally also store your own copy of the resulting artifact.
How do I find all valid revisions for a repo without guessing?
Use huggingface_hub's list_repo_refs to programmatically list every valid branch and tag, or browse the Files and versions tab and commit history directly on the model's HuggingFace page, rather than relying on documentation examples that may reference a different repo or an outdated revision.
Does this same issue apply to datasets, not just models?
Yes, dataset repos on the Hub use the identical git-based revisioning system, so the same causes (wrong repo's hash, rewritten history, renamed files between revisions) and the same diagnostic approach with list_repo_refs and list_repo_files apply equally to pinned dataset revisions.
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.
Related problems
401/403 Unauthorized pulling a gated model from HuggingFace
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.
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.
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.
trust_remote_code required, and the security tradeoff behind that error
This error is transformers deliberately refusing to run arbitrary Python code from a model repository without explicit consent, because loading such a model means executing the repository author's custom modeling_*.py file directly in your process with full permissions, not just deserializing tensor data. Passing trust_remote_code=True removes the error but does not remove the risk; in a regulated or air-gapped environment the correct approach is to review that code yourself, vendor a pinned copy of it, and only then load with trust_remote_code=True against your reviewed copy.
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.
GuideThe Model Upgrade Migration Playbook
A playbook for upgrading production LLMs: re-evaluation, prompt regression testing, rollback planning, and avoiding silent quality regressions.
GuideAir-Gapped Model Updates: A Patching Guide
Air-gapped model updates for enterprise AI: secure transfer procedures, hash verification, and staged rollout so patches never introduce risk.
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.