Blog
7 min read

Git "error: cannot lock ref": What Causes It and How to Fix It

Git error cannot lock ref usually means a stale remote branch, a branch name clash, or a leftover .lock file. How to read the message and fix each case safely.

error: cannot lock ref means Git tried to update a branch or tag pointer and something in the way stopped it. In most cases the fix is git remote prune origin (to clear out stale remote branches) or deleting a leftover .lock file after checking no other Git process is running. The text after the colon tells you which case you have.

What a "ref" is and why Git locks it

A ref is a name that points at a commit: refs/heads/main is your local main branch, refs/remotes/origin/main is your copy of what main looked like on the remote last time you fetched. In the default storage format, each ref is a small file inside .git/refs/, and a branch called feature/login is literally a file called login inside a folder called feature.

Before Git changes a ref, it creates a lock file next to it (main.lock), writes the new value there, and renames it into place. If it can't create that lock, or the ref isn't in the state Git expected, you get "cannot lock ref".

Because refs are files and folders, the usual filesystem rules apply. That explains almost every cause below.

Read the second half of the message

The error always has the shape cannot lock ref '<ref name>': <reason>. Match the reason to a section:

Reason after the colon Section
'refs/remotes/origin/foo' exists; cannot create 'refs/remotes/origin/foo/bar' Branch name is a prefix of another
Unable to create '.../main.lock': File exists. Leftover lock file
is at <hash> but expected <hash> Stale or clashing ref (often case-insensitive filesystems)
reference already exists You're creating something that already exists

Cause 1: a branch name that is a prefix of another (foo and foo/bar)

This is the most common one during git fetch or git pull:

error: cannot lock ref 'refs/remotes/origin/foo/bar': 'refs/remotes/origin/foo' exists; cannot create 'refs/remotes/origin/foo/bar'
 ! [new branch]      foo/bar    -> origin/foo/bar  (unable to update local ref)

Someone deleted the branch foo on the remote and created foo/bar. Your machine still has the old origin/foo as a file, so Git can't create a folder with the same name to hold foo/bar.

The fix is to delete remote-tracking branches that no longer exist on the remote:

git remote prune origin --dry-run   # shows what would be removed
git remote prune origin

or do it while fetching:

git fetch --prune

Both only touch your origin/... copies, never your own local branches or commits. According to the git-fetch docs, you can make this automatic with:

git config --global fetch.prune true

The same clash can happen with your local branches. If you have a local branch foo, git branch foo/bar fails with 'refs/heads/foo' exists; cannot create 'refs/heads/foo/bar'. Rename or delete one of them (see how to delete a Git branch), or pick a name that doesn't nest.

Cause 2: a leftover .lock file

error: cannot lock ref 'refs/heads/main': Unable to create '/home/you/project/.git/refs/heads/main.lock': File exists.

Another git process seems to be running in this repository, e.g.
an editor opened by 'git commit'. ...

Either another Git command really is running (an editor waiting for a commit message, your IDE's background fetch, a Git GUI), or a previous Git process crashed or was killed and left its lock behind.

Safe order:

  1. Close editors and Git GUIs, and check for running Git processes:
    ps aux | grep -i '[g]it'
    
    On Windows, look in Task Manager for git.exe.
  2. Try the command again. If a process was holding the lock, it's gone now.
  3. If nothing is running and it still fails, delete the specific lock file named in the error:
    rm .git/refs/heads/main.lock
    

To find any other stale ref locks:

find .git -name '*.lock'

Only delete lock files when you're sure no Git process is running. Removing a lock that's in active use lets two processes write the same ref at once, which is exactly what the lock exists to prevent. Never delete anything else in .git as part of this fix.

Cause 3: branch names that differ only by case

macOS and Windows filesystems are usually case-insensitive: Feature and feature are the same folder. Git itself treats branch names as case-sensitive. So if the remote has both Feature/login and feature/login (often created by two people, or by a tool that capitalised a name), your machine can't store both as separate files. Fetch fails with cannot lock ref, frequently with is at <hash> but expected <hash>, and the error can keep coming back on every fetch.

Fix it at the source:

  1. Agree with the team which name to keep, then delete the other on the remote (from a Linux machine, the GitHub/GitLab web UI, or git push origin --delete Feature/login).
  2. Remove your stale local copy of the deleted one and prune:
    git update-ref -d refs/remotes/origin/Feature/login
    git fetch --prune
    

git update-ref -d deletes just that one remote-tracking ref. It does not delete the branch on the remote or any commits.

Going forward, a team rule of lower-case branch names avoids this entirely. Our Git branches explained post covers naming.

Cause 4: a stale or out-of-date remote-tracking ref

is at <hash> but expected <hash> means the ref changed between Git reading it and Git trying to update it. Besides the case clash above, this happens when two Git processes run at once (an IDE auto-fetching while you run git pull in the terminal), or after an interrupted fetch.

Usually just running the command again fixes it. If it keeps failing on one remote-tracking branch, delete your copy of that ref and fetch it fresh:

git update-ref -d refs/remotes/origin/some-branch
git fetch origin

This is safe for refs/remotes/... because those are only copies of what's on the server. Don't do this to refs/heads/... (your own branches) unless you know the commits are also reachable elsewhere.

The tidy-up: git gc --prune=now

If you still see errors after pruning, a garbage collection run can help. git gc packs loose ref files into a single packed-refs file and cleans up unreachable objects:

git gc --prune=now

The git-gc docs warn that --prune=now "increases the risk of corruption if another process is writing to the repository concurrently". Close your IDE and any other Git tools first. If you aren't sure, plain git gc (which keeps recent loose objects for two weeks by default) is the safer choice.

gc doesn't fix a name clash: two refs that collide on a case-insensitive disk still collide. It tidies things up after you've fixed the clash.

Quick checklist

  1. Read the reason after cannot lock ref '...':.
  2. exists; cannot create → git remote prune origin (or rename your local branch).
  3. .lock': File exists → make sure no Git process is running, then delete that one lock file.
  4. Case-only differences → delete one of the branches on the remote, git update-ref -d the stale copy, prune.
  5. is at ... but expected → retry, then delete and re-fetch that remote-tracking ref.
  6. Still messy → close other Git tools and run git gc --prune=now.

If fetch and pull themselves are still a bit fuzzy, git fetch vs git pull explains what remote-tracking branches are, and how to undo almost anything in Git is useful when a fix goes sideways.

EasySpawn runs your repo on a Linux cloud server with a case-sensitive filesystem, so branch names that differ only by case don't collide there. See how it works or join the waitlist.

Related: How to Delete a Git Branch (Local and Remote) · Git Branches Explained for Beginners · Git Fetch vs Git Pull: What's the Difference? · How to Undo Almost Anything in Git (Including an AI Agent's Mess)

Keep reading