How to fix fatal: HEAD is broken in Git

GitINTERMEDIATEMEDIUMUpdated Dec 2, 2025· 121 views

The git describe --broken command reports a broken worktree when Git cannot determine if local modifications exist due to repository corruption, broken submodules, or index issues.

Quick fix

Fixes fatal: HEAD is broken

git fsck --full
  1. Verify repository corruption with fsck
  2. Refresh the index
  3. Check submodule status
  4. Repair worktree connections
git — error
git fsck --full
fatal: HEAD is broken

What this error means

The --broken flag in git describe is designed to handle situations where Git cannot reliably determine the state of your working tree. Introduced in Git 2.13, this flag prevents fatal errors when the repository is in a corrupted state or when submodules are broken. When git describe --dirty would normally crash trying to check for modifications, git describe --broken instead appends "-broken" to the output, allowing you to retrieve version information even from a damaged repository. This error typically manifests when Git encounters severe issues: corrupted repository objects, broken or missing submodule references, or an index file that cannot be properly read. The command spawns a child process to check for dirtiness, and if that process dies unexpectedly, Git knows something is fundamentally wrong with the repository state. Understanding this distinction is crucial: --dirty detects uncommitted changes in a healthy repository, while --broken detects when Git itself cannot determine the repository health status.

Typical symptoms

  • git describe --dirty command crashes with fatal error
  • Output shows "-broken" suffix instead of expected version tag
  • Git commands report HEAD or index corruption
  • Submodule operations fail unexpectedly
  • Working tree state cannot be determined by Git status
  • CI/CD pipelines fail during version tagging steps

Common causes

  1. Corrupted repository objects or broken HEAD reference
  2. Broken or improperly initialized submodules
  3. Stale or corrupted index file (particularly in Git 1.7.6 and earlier)
  4. Filesystem issues preventing Git from reading repository metadata
  5. Interrupted Git operations that left repository in inconsistent state
  6. Worktree administrative files that are outdated or corrupted
  7. Files marked with --assume-unchanged flag causing detection issues

How to fix "fatal: HEAD is broken"

1Verify repository corruption with fsck

Run Git's filesystem check to identify any corrupted objects or broken references:

bash
git fsck --full

This will report any dangling commits, broken links, or corrupted objects. Look for messages starting with "error:" or "fatal:". If fsck completes without errors, the corruption may be in the index or worktree configuration rather than the object database.

2Refresh the index

Stale index files are a common cause, especially in older Git versions. Refresh it manually:

bash
git update-index --refresh

Then try your git describe command again. This forces Git to re-scan the working directory and update its internal state cache.

3Check submodule status

If you're using submodules, verify their integrity:

bash
git submodule status
git submodule update --init --recursive

Broken submodules are one of the primary reasons git describe --broken was introduced. If submodules show errors, reinitialize them or repair their .git references.

4Repair worktree connections

If using linked worktrees and the main repository has moved, repair the connections:

bash
git worktree repair

This reestablishes links between the main worktree and any linked worktrees that may have become disconnected.

5Clear assume-unchanged flags

Files marked with --assume-unchanged can interfere with state detection. List and clear them:

bash
# List files with assume-unchanged flag
git ls-files -v | grep "^h"

# Clear the flag for specific files
git update-index --no-assume-unchanged path/to/file

Repeat for all affected files, then retry git describe.

6Recover from severe corruption

If fsck revealed corrupted objects, attempt recovery:

bash
# Create backup first
cp -r .git .git.backup

# Try automatic repair
git reflog expire --expire=now --all
git gc --prune=now --aggressive

For more severe corruption, you may need to clone fresh from a remote and reapply local changes. Always backup before attempting deep repairs.

Advanced notes

The --broken flag was specifically designed for CI/CD environments where you need version information even when repository integrity is questionable. In automated builds, failing fast with git describe --dirty can break pipelines unnecessarily, while git describe --broken --dirty allows the build to continue while flagging the issue.

For scripts that need to detect both dirty and broken states across submodules, use: git describe --broken --dirty --all combined with git submodule foreach. This provides comprehensive state detection across your entire repository tree.

In Git 2.41 and later, sparse-index support improves performance of git describe --dirty in large repositories. If you're working with monorepos or partial checkouts, ensure you're using a recent Git version.

The child process approach used by --broken means it's slightly slower than --dirty alone, but the tradeoff is resilience against repository corruption. In performance-critical scripts, only use --broken when you suspect repository integrity issues.

Frequently asked questions

What does "fatal: HEAD is broken" mean?
The --broken flag in git describe is designed to handle situations where Git cannot reliably determine the state of your working tree. 13, this flag prevents fatal errors when the repository is in a corrupted state or when submodules are broken. When git describe --dirty would normally crash trying to check for modifications, git describe --broken instead appends "-broken" to the output, allowing you to retrieve version information even from a damaged repository.
How do I fix "fatal: HEAD is broken"?
The git describe --broken command reports a broken worktree when Git cannot determine if local modifications exist due to repository corruption, broken submodules, or index issues.
What causes "fatal: HEAD is broken"?
Corrupted repository objects or broken HEAD reference Broken or improperly initialized submodules Stale or corrupted index file (particularly in Git 1.7.6 and earlier)
Is the "fatal: HEAD is broken" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading