Git "fatal: couldn't find remote ref" in CI
Git asked the remote for a specific ref and the remote does not have it. The branch or tag name is wrong, was deleted, or the ref simply was never created on the remote you are pointing at.
What this error means
A fetch or checkout of a named ref fails with fatal: couldn't find remote ref <ref>. Other refs in the same repo fetch fine - only this branch/tag/SHA is missing on the remote.
fatal: couldn't find remote ref refs/heads/relase-2.0
# or
fatal: couldn't find remote ref v1.2.3Common causes
The branch or tag name is wrong or deleted
A typo (relase vs release), a branch that was merged and deleted, or a tag that was never pushed all mean the remote has no such ref to return.
The default branch was renamed
A job hard-coded to master fails against a repo whose default branch is now main (or vice versa). The old name no longer exists on the remote.
Tags were never fetched
A shallow or --no-tags clone may not know about a tag, so a checkout of that tag asks the remote for a ref the local clone never mirrored.
How to fix it
List what the remote actually has
Confirm the exact ref name before checking it out.
git ls-remote --heads --tags https://github.com/org/repo.git
# grep for the branch/tag you expectReference the correct ref
- Fix typos and use the repo’s real default branch (
mainvsmaster). - For tag checkouts, ensure tags are fetched (
fetch-tags: trueorgit fetch --tags). - In a workflow, use a context value (e.g. the default branch) instead of hard-coding a branch name.
How to prevent it
- Derive the default branch dynamically instead of hard-coding
main/master. - Fetch tags when a job checks out tagged releases.
- Validate ref names with
git ls-remotein scripts that take a branch/tag input.