How to fix error: index file corrupt, needs refresh in Git

GitBEGINNERMEDIUMUpdated Dec 2, 2025· 247 views

Git reports the index needs refresh when cached file metadata becomes stale or mismatched with the working tree, commonly after switching environments, interrupted operations, or cross-platform development.

Quick fix

Fixes error: index file corrupt, needs refresh

git update-index --refresh
  1. Refresh the index to resync cached metadata
  2. Use really-refresh for stubborn cases
  3. Clear unresolved merge conflicts if present
  4. Remove orphaned index.lock file if Git process crashed
git — error
git update-index --refresh
error: index file corrupt, needs refresh

What this error means

The Git index (also called the staging area or cache) maintains cached metadata about files in your repository, including timestamps, file sizes, and inode numbers. This cache allows Git to quickly determine if files have changed without reading their entire contents. When Git detects that the cached metadata in the index doesn't match the actual filesystem state, it reports that the index needs refresh. This is Git's way of saying "I can't trust my cached data anymore and need to re-examine the files." This error is usually harmless and indicates a mismatch in cached statistics rather than actual corruption. Git uses the index as a performance optimization, so when the cache becomes invalid, it simply needs to be rebuilt with current information.

Typical symptoms

  • Git commands report "index file corrupt, needs refresh"
  • Git status shows modified files that haven't actually changed
  • Operations fail with "error: index needs an update"
  • Git commands become slower as they constantly refresh the index
  • Index refresh messages appear when switching between Windows and WSL
  • IDE or editor triggers frequent index updates

Common causes

  1. Switching between different operating systems (Windows/Linux/WSL) on the same repository
  2. Filesystem metadata differs between environments (inode numbers, timestamps, permissions)
  3. Git process was terminated abruptly during an index operation
  4. Using network filesystems (NFS, SMB) with clock skew or caching issues
  5. IDE or editor running background Git commands that touch the index
  6. System clock changes or timezone differences affecting file timestamps
  7. Interrupted merge, rebase, or stash operation leaving index in inconsistent state
  8. The "racy Git" problem: file modified within same second as index update

How to fix "error: index file corrupt, needs refresh"

1Refresh the index to resync cached metadata

The quickest solution is to explicitly refresh the index, forcing Git to re-read filesystem metadata:

bash
git update-index --refresh

If you want to suppress error output and continue anyway:

bash
git update-index -q --refresh

This re-matches file statistics with the index without recalculating content hashes.

2Use really-refresh for stubborn cases

If the standard refresh doesn't work, use the --really-refresh option which ignores the "assume-unchanged" flag:

bash
git update-index --really-refresh

This checks stat information unconditionally, regardless of cached assumptions.

3Clear unresolved merge conflicts if present

If the error occurred during a merge, rebase, or stash operation, check for unmerged files:

bash
git status

If you see unmerged paths, either add them after resolving conflicts:

bash
git add <file>

Or reset them if you don't want the changes:

bash
git reset -- <file>
4Remove orphaned index.lock file if Git process crashed

If a Git process was terminated unexpectedly, it may leave behind an orphaned lock file:

bash
rm -f .git/index.lock

Then retry your operation. Only do this if you're certain no Git process is running.

5For cross-platform issues, use consistent Git binary

When working with WSL, consider using the Windows Git binary consistently:

bash
# In WSL, create an alias to use Windows Git
alias git=git.exe

Or create a wrapper script at /usr/local/bin/git that chooses the appropriate binary based on whether you're in /mnt (Windows drives) or native Linux paths.

Advanced notes

The Racy Git Problem: Git's index uses file modification times (mtime) with typically one-second resolution. If a file is modified within the same second as an index update, Git cannot reliably determine if the file changed based on mtime alone. Files in this state are called "racily clean" and Git must read their full contents to verify. This is documented in Documentation/technical/racy-git.txt in the Git source.

Cross-Platform Metadata Differences: The index caches platform-specific data like inode numbers (Linux/macOS) which don't exist on Windows. When you access the same repository from different platforms, this cached metadata becomes completely invalid, forcing frequent refreshes. This is expected behavior, not a bug.

Background IDE Processes: Modern IDEs like VS Code, Emacs with Magit, or JetBrains products run periodic Git status checks in the background. These touch the index and can cause frequent refresh cycles. You can optimize this by configuring your IDE to use git --no-optional-locks status to prevent unnecessary index locking.

Network Filesystem Considerations: Repositories on NFS, SMB, or cloud-synced folders (Dropbox, OneDrive) are especially prone to index refresh issues due to caching layers, clock skew between client/server, and delayed metadata updates. For best performance, keep Git repositories on local filesystems.

Frequently asked questions

What does "error: index file corrupt, needs refresh" mean?
The Git index (also called the staging area or cache) maintains cached metadata about files in your repository, including timestamps, file sizes, and inode numbers. This cache allows Git to quickly determine if files have changed without reading their entire contents. When Git detects that the cached metadata in the index doesn't match the actual filesystem state, it reports that the index needs refresh.
How do I fix "error: index file corrupt, needs refresh"?
Git reports the index needs refresh when cached file metadata becomes stale or mismatched with the working tree, commonly after switching environments, interrupted operations, or cross-platform development.
What causes "error: index file corrupt, needs refresh"?
Switching between different operating systems (Windows/Linux/WSL) on the same repository Filesystem metadata differs between environments (inode numbers, timestamps, permissions) Git process was terminated abruptly during an index operation
Is the "error: index file corrupt, needs refresh" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading