Unable to Create .git/index.lock File Exists: Safe Git Check + Claude Code 2.1.314 Fix

Git or Claude Code suddenly prints fatal: Unable to create '.../.git/index.lock': File exists. Do not delete the lock file first. There are two layers: a normal git lock, and a Claude Code bug fixed in 2.1.314 where background diff refresh briefly held the index lock.

What I saw: in a throwaway repo at /tmp/gitlockdemo I created an empty .git/index.lock and ran git status; the full fatal message matched Git’s usual wording (quoted below). This box still runs Claude Code 2.1.312, so the background-diff fix needs an upgrade to 2.1.314.

What the error means

Git uses .git/index.lock so only one process updates the index at a time. While the lock exists, new git commands refuse to create another and tell you another git may still be running — or a crashed process left the file behind.

A short FAQ belongs on Claude Code Errors; this page covers the Claude Code-specific layer and a safe check-before-delete sequence.

What we reproduced

After git init and one commit in an empty folder:

touch .git/index.lock
git status

Output I saw (excerpt):

fatal: Unable to create '/tmp/gitlockdemo/.git/index.lock': File exists.

Another git process seems to be running in this repository, e.g.
an editor opened by 'git commit'. Please make sure all processes
are terminated then try again. If it still fails, a git process
may have crashed in this repository earlier:
remove the file manually to continue.

Only after confirming no git writer was running did we remove the lock; then git status worked again. The demo repo was disposable.

Two layers

1. Normal git lock (any tool)

Another git commit / git merge / IDE git is running, or a crash left the lock. Sequence:

1. Look for git-related processes.

2. Wait for the legitimate operation to finish.

3. If nothing is writing the repo, remove .git/index.lock.

Do not blind-rm the lock while a writer may still be active — you can corrupt the index.

2. Claude Code background diff refresh (fixed in 2.1.314)

CHANGELOG 2.1.314: background diff refreshes briefly took the repository’s index lock, so a concurrent git command could fail with Unable to create .git/index.lock: File exists. After the fix, that path should stop recurring.

I inferred: if locks appear mainly while Claude Code is open and your build is < 2.1.314, upgrade first; if they continue, treat them as layer 1.

Version on this box:

claude --version
# 2.1.312 (Claude Code)

Recommended steps

1. Confirm the path is this repo’s .git/index.lock.

2. Check for a live git / editor git operation.

3. No writer → delete the lock → retry.

4. Recurring under Claude Code → upgrade to ≥ 2.1.314.

5. Other errors: error hub; effort 400: Invalid effort level.

FAQ

Can I just rm .git/index.lock?

Only after you are sure no git process is writing this repository. Git’s own message says the same. Our demo checked processes first.

Is this the same as “working directory no longer exists”?

No. A moved or deleted folder is a different failure. Writes outside working directories are covered in Claude Code /permissions and blockWrites (when that post is live).

I searched for a generic “git index.lock file exists”

Use the hub FAQ for the generic case; use this page when you need the Claude Code background-diff angle. Hub: Claude Code Errors.