Introduction

An invalid remote branch reference in Git usually means your local remote-tracking metadata no longer matches the server. That often happens after branch deletion, force-pushes, repository migrations, or interrupted fetch operations. The fix is usually to prune stale refs first, then delete a specific broken ref only if pruning does not clean it up.

Start With Pruning

The safest first step is to ask Git to remove remote-tracking branches that no longer exist on the server.

git fetch origin --prune
git remote prune origin
git branch -r

In many cases, that is enough. Git removes stale references under refs/remotes/origin/..., and the warning disappears on the next fetch.

Understand What You Are Deleting

A remote-tracking ref is not the same thing as a local branch. Deleting your local branch does not fix a corrupt or stale remote-tracking entry.

To inspect what Git currently knows about remote refs:

git show-ref | grep refs/remotes/origin
git remote show origin

If the error mentions a specific ref path such as refs/remotes/origin/feature/old-branch, keep that exact path and use it in the cleanup step.

Delete a Specific Broken Ref Safely

If prune does not fix the issue, remove the ref with Git's own plumbing instead of editing files inside .git by hand.

git update-ref -d refs/remotes/origin/feature/old-branch
git fetch origin --prune

git update-ref -d is the safer way to delete one ref because Git updates its internal reference state consistently.

Packed Refs Can Make the Problem Less Obvious

Some refs are not stored as separate files. They may be packed into .git/packed-refs, which is why deleting a file under .git/refs is not always enough.

That is another reason to prefer Git commands over manual file edits.

If the repository metadata is messy, repacking and garbage collection can help after pruning:

git pack-refs --all --prune
git gc --prune=now

These commands do not change server history. They clean local metadata.

Check the Remote Refspec Too

Sometimes the recurring problem is not the ref itself but a strange fetch refspec that keeps recreating unwanted mappings.

Inspect the configured fetch rules:

git config --get-all remote.origin.fetch
git remote -v

A normal default fetch refspec looks like this:

+refs/heads/*:refs/remotes/origin/*

If the repository contains old custom refspecs from a migration or unusual branch namespace setup, clean them up and fetch again.

git config --unset-all remote.origin.fetch
git config --add remote.origin.fetch '+refs/heads/*:refs/remotes/origin/*'
git fetch origin --prune

Enable Automatic Pruning

If stale remote refs accumulate repeatedly, enable pruning by default.

git config fetch.prune true
git config --global fetch.prune true

The repository-level command affects only the current repo. The global command sets the habit for all repos on the machine.

When Recloning Is Faster

If the local ref database is badly damaged or the repository has been through unusual migration issues, recloning can be faster than chasing every stale reference manually. That should be a last resort, not the first move.

Before recloning, preserve any uncommitted work:

git status
git stash push -u -m "temporary-save-before-reclone"

Then create a fresh clone in a new directory instead of trying to reuse a suspicious .git state.

Common Pitfalls

A common mistake is deleting local branches when the problem is actually under refs/remotes. Those are different things.

Another issue is editing .git/refs files directly. That sometimes appears to work, but it is easy to create more inconsistencies, especially when packed refs are involved.

Teams also forget that case-only branch name differences can create confusing ref problems on case-insensitive file systems.

Summary

• Start with git fetch --prune or git remote prune origin.
• If needed, delete the exact broken remote-tracking ref with git update-ref -d.
• Prefer Git plumbing commands over manual edits inside .git.
• Check unusual fetch refspecs if the bad ref keeps returning.
• Enable automatic pruning so stale remote refs do not accumulate again.