How to fix fatal: circular reference detected in symbolic ref in Git

GitADVANCEDHIGHUpdated Dec 7, 2025· 124 views

Git has detected that symbolic references form a loop, where ref A points to ref B, which eventually points back to ref A. This prevents Git from resolving the final target commit.

Quick fix

Fixes fatal: circular reference detected in symbolic ref

# Check what HEAD points to
cat .git/HEAD

# List all symbolic refs
find .git/refs -type f -exec sh -c 'echo "=== {} ===" && cat {}' ;

# Check for symref loops
git symbolic-ref HEAD
  1. Identify the circular reference chain
  2. Back up your repository
  3. Break the circular reference
  4. Verify repository integrity
git — error
# Check what HEAD points to
cat .git/HEAD
# List all symbolic refs
find .git/refs -type f -exec sh -c 'echo "=== {} ===" && cat {}' ;
# Check for symref loops
git symbolic-ref HEAD
fatal: circular reference detected in symbolic ref

What this error means

This error occurs when Git encounters a chain of symbolic references that creates an infinite loop. In Git, a symbolic reference (symref) is a reference that points to another reference rather than directly to a commit hash. For example, HEAD is typically a symref that points to refs/heads/main. Git allows chained symbolic references up to a depth of 5 levels to enable legitimate use cases. However, when these references form a circular chain (A → B → C → A), Git cannot resolve them to an actual commit hash and raises this fatal error. This is a protective mechanism to prevent infinite loops during reference resolution. The error indicates that your repository's reference structure has become corrupted, often due to manual manipulation of refs, file system issues, or interrupted Git operations.

Typical symptoms

  • Git commands fail with "fatal: circular reference detected"
  • Unable to check out branches or view commit history
  • git symbolic-ref commands fail or loop indefinitely
  • Repository appears broken or inaccessible
  • git fsck reports circular reference issues

Common causes

  1. Manual editing of .git/refs files or .git/HEAD creating circular links
  2. File system corruption affecting reference files
  3. Interrupted git operations that left refs in inconsistent state
  4. Automated scripts incorrectly modifying symbolic references
  5. Repository cloning or migration errors that corrupted ref structure
  6. Using low-level plumbing commands incorrectly (git symbolic-ref, git update-ref)

How to fix "fatal: circular reference detected in symbolic ref"

1Identify the circular reference chain

First, examine your repository's symbolic references to identify which refs are involved in the loop:

bash
# Check what HEAD points to
cat .git/HEAD

# List all symbolic refs
find .git/refs -type f -exec sh -c 'echo "=== {} ===" && cat {}' ;

# Check for symref loops
git symbolic-ref HEAD

If git symbolic-ref HEAD fails with the circular reference error, HEAD is involved in the loop. Look for refs that start with "ref:" and trace their chain.

2Back up your repository

Before making any changes, create a backup of your .git directory:

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

# Or create a tarball
tar -czf git-backup-$(date +%Y%m%d-%H%M%S).tar.gz .git

This allows you to restore if something goes wrong during the repair.

3Break the circular reference

Manually fix the circular reference by pointing one of the refs directly to a commit hash:

bash
# If HEAD is involved, point it to your main branch's commit
git log --all --oneline | head -5  # Find a recent commit hash

# Manually set HEAD to point to the main branch
echo "ref: refs/heads/main" > .git/HEAD

# Or point HEAD directly to a commit hash temporarily
echo "commit-hash-here" > .git/HEAD

If the circular reference involves branch refs rather than HEAD:

bash
# Delete the problematic ref
rm .git/refs/heads/problematic-branch

# Recreate it pointing to the correct commit
git branch problematic-branch commit-hash
4Verify repository integrity

After breaking the circular reference, verify that your repository is healthy:

bash
# Check repository integrity
git fsck --full

# Verify symbolic references work
git symbolic-ref HEAD

# Test basic operations
git status
git log --oneline -5

# List all branches
git branch -a

If git fsck reports no errors and basic commands work, the circular reference has been resolved.

5Restore proper branch structure

If you had to point HEAD directly to a commit hash, reattach it to a proper branch:

bash
# Create or checkout the intended branch
git checkout -b main  # If branch doesn't exist
# or
git checkout main     # If branch exists

# Verify HEAD is now a symbolic ref
cat .git/HEAD
# Should show: ref: refs/heads/main

For any other affected branches, recreate them using git branch branch-name commit-hash.

Advanced notes

### Understanding Git's Symbolic Reference Depth Limit

Git explicitly allows chained symbolic references up to a depth of 5 levels (including HEAD). This means you can have HEAD → branch-alias → actual-branch → commit, with a few levels to spare. The circular reference check protects against infinite loops while allowing legitimate use cases.

### Using Low-Level Plumbing Commands Safely

If you need to manipulate symbolic references programmatically, always use Git's plumbing commands rather than editing files directly:

bash
# Safe: Create/update a symbolic ref
git symbolic-ref refs/heads/alias refs/heads/main

# Safe: Delete a symbolic ref
git symbolic-ref --delete refs/heads/alias

# Unsafe: Direct file manipulation
echo "ref: refs/heads/something" > .git/refs/heads/alias  # Risky

### Dangling vs Circular References

Don't confuse circular references with dangling symbolic references. A dangling symref points to a branch that doesn't exist yet (common in new repositories where HEAD points to refs/heads/main before the first commit). Dangling refs are harmless; circular refs are fatal errors.

### Prevention in Automation

If you're writing scripts that manipulate Git refs, always validate that you're not creating circular chains:

bash
# Check if a ref is symbolic before modifying
if git symbolic-ref --quiet refs/heads/branch; then
  echo "This is a symbolic ref"
  # Handle accordingly
fi

Frequently asked questions

What does "fatal: circular reference detected in symbolic ref" mean?
This error occurs when Git encounters a chain of symbolic references that creates an infinite loop. In Git, a symbolic reference (symref) is a reference that points to another reference rather than directly to a commit hash. For example, HEAD is typically a symref that points to refs/heads/main.
How do I fix "fatal: circular reference detected in symbolic ref"?
Git has detected that symbolic references form a loop, where ref A points to ref B, which eventually points back to ref A. This prevents Git from resolving the final target commit.
What causes "fatal: circular reference detected in symbolic ref"?
Manual editing of .git/refs files or .git/HEAD creating circular links File system corruption affecting reference files Interrupted git operations that left refs in inconsistent state
Is the "fatal: circular reference detected in symbolic ref" 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