How to fix error: bad ref for .git/refs/heads/main in Git

GitINTERMEDIATEHIGHUpdated Dec 6, 2025· 173 views

This error occurs when a Git branch reference file becomes corrupted, typically due to a system crash, power failure, or disk error. The fix involves deleting the corrupted ref file and recovering from the reflog or remote.

Quick fix

Fixes error: bad ref for .git/refs/heads/main

git fsck --full
  1. Identify the corrupted ref file
  2. Check the reflog for the correct SHA
  3. Delete the corrupted ref file
  4. Restore the ref from reflog
git — error
git fsck --full
error: bad ref for .git/refs/heads/main

What this error means

Git stores branch references as small text files in the `.git/refs/heads/` directory. Each file contains the 40-character SHA-1 hash of the commit that branch points to. When Git reports "bad ref for .git/refs/heads/main" (or another branch name), it means the reference file exists but contains invalid data. This corruption typically happens when your system loses power or crashes while Git is writing to a ref file. The file may end up containing null bytes, partial data, or be completely empty. Git cannot parse this as a valid commit reference, so it reports the ref as "bad." The good news is that Git's design makes this recoverable in most cases. The actual commit data is stored separately in Git's object database, and the reflog (stored in `.git/logs/`) keeps a history of what each ref pointed to. You can usually restore the correct SHA-1 from these backups.

Typical symptoms

  • Git commands fail with 'error: bad ref for .git/refs/heads/<branch>'
  • Running 'git status' or 'git branch' produces errors
  • 'git gc' fails with 'fatal: bad object refs/heads/<branch>'
  • 'git fsck' reports corrupted or invalid refs
  • The error appeared after a system crash, power outage, or forced shutdown

Common causes

  1. System crash or power failure while Git was writing to a ref file (most common)
  2. Disk write failure or filesystem corruption
  3. External process or editor modifying .git directory files
  4. Incomplete Git operation interrupted by Ctrl+C or process kill
  5. Storage device disconnected during Git operation (USB drives, network mounts)
  6. Antivirus software quarantining or modifying .git files

How to fix "error: bad ref for .git/refs/heads/main"

1Identify the corrupted ref file

First, run git fsck to identify all corrupted references:

bash
git fsck --full

This will list all problematic refs. You can also check the specific file mentioned in the error:

bash
cat .git/refs/heads/main

If the file is corrupted, you'll see null characters, garbage data, or an empty output instead of a 40-character SHA-1 hash.

2Check the reflog for the correct SHA

Git's reflog tracks recent changes to each ref. Check if the correct SHA is preserved:

bash
# View the reflog for the corrupted branch
tail -n 5 .git/logs/refs/heads/main

# Or use git reflog (may fail if HEAD is also corrupted)
git reflog show main

The reflog entries look like this:

bash
abc1234 def5678 User <email> 1234567890 +0000  commit: message

The second SHA (def5678... in full 40-character form) is the most recent commit for that ref.

3Delete the corrupted ref file

Once you've identified the correct SHA (or confirmed you can recover from remote), delete the corrupted file:

bash
# Remove the corrupted ref
rm .git/refs/heads/main

# If the logs file is also corrupted, remove it too
rm .git/logs/refs/heads/main

Important: Only delete the specific corrupted files, not the entire refs directory.

4Restore the ref from reflog

If you found the correct SHA in the reflog, restore the branch:

bash
# Replace <sha> with the 40-character SHA from your reflog
git update-ref refs/heads/main <sha>

# Example:
git update-ref refs/heads/main a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0

Verify the restoration:

bash
git log main --oneline -5
5Recover from remote (if reflog unavailable)

If you can't find the SHA in the reflog, fetch from the remote repository:

bash
# Fetch all refs from origin
git fetch origin

# Recreate the local branch from the remote
git branch -f main origin/main

# Or checkout the branch
git checkout -B main origin/main

This will reset your local branch to match the remote, so any unpushed commits will be lost.

6Run garbage collection

After fixing the refs, clean up the repository:

bash
git gc --prune=now

Then verify everything is working:

bash
git fsck --full
git status

If git fsck reports no errors, your repository is healthy again.

7Prune stale remote refs (optional)

If the corrupted refs were remote tracking branches, prune them:

bash
git remote prune origin

This removes any local references to remote branches that no longer exist.

8Last resort: Clone fresh and copy changes

If multiple refs are corrupted and recovery is difficult, clone a fresh copy:

bash
# Clone the repository fresh
git clone <repository-url> project-fresh

# Copy any uncommitted changes from the old repo
cp -r old-project/src/* project-fresh/src/

# Verify and commit your changes
cd project-fresh
git status
git add .
git commit -m "Recover uncommitted changes"

This approach preserves all committed history from the remote while recovering your local changes.

Advanced notes

### Understanding Git Refs

Git refs are simple text files that map human-readable names to commit SHAs:
- .git/refs/heads/ - Local branches
- .git/refs/remotes/ - Remote tracking branches
- .git/refs/tags/ - Tags
- .git/HEAD - Currently checked out branch/commit

### Packed Refs

For performance, Git may "pack" refs into a single file at .git/packed-refs. If your branch is packed, you may need to edit this file directly:

bash
# Check if branch is in packed-refs
grep "refs/heads/main" .git/packed-refs

# Edit if necessary (use the correct SHA)
# Format: <sha> refs/heads/main

### Preventing Future Corruption

1. Use a UPS for systems with important repositories
2. Sync before shutdown: Run git fsck before shutting down
3. Avoid force-killing Git: Let Git operations complete
4. Keep remotes up to date: Push frequently so you have a backup
5. Consider filesystem journaling: ext4, XFS, or NTFS with journaling enabled

### Using git-repair Tool

On Debian/Ubuntu systems, you can install a dedicated repair tool:

bash
sudo apt install git-repair
git-repair

This tool automatically attempts to fix common repository corruption issues.

### WSL and Windows Considerations

If using Git in WSL accessing Windows filesystem (e.g., /mnt/c/), corruption is more likely due to cross-filesystem operations. Keep repositories within the WSL filesystem (~/) for better reliability.

Frequently asked questions

What does "error: bad ref for .git/refs/heads/main" mean?
git/refs/heads/ directory. Each file contains the 40-character SHA-1 hash of the commit that branch points to. git/refs/heads/main" (or another branch name), it means the reference file exists but contains invalid data.
How do I fix "error: bad ref for .git/refs/heads/main"?
This error occurs when a Git branch reference file becomes corrupted, typically due to a system crash, power failure, or disk error. The fix involves deleting the corrupted ref file and recovering from the reflog or remote.
What causes "error: bad ref for .git/refs/heads/main"?
System crash or power failure while Git was writing to a ref file (most common) Disk write failure or filesystem corruption External process or editor modifying .git directory files
Is the "error: bad ref for .git/refs/heads/main" error serious?
Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.

Official resources & further reading