This Git error occurs when HEAD cannot reference a valid commit, typically in a newly initialized repository with no commits, or when the HEAD reference has become corrupted. The fix usually involves making an initial commit or resetting HEAD to a valid branch.
When Git displays "fatal: Not a valid object name: 'HEAD'", it means the HEAD reference in your repository does not point to a valid commit object. HEAD is a special pointer that Git uses to track your current position in the repository's commit history. This error most commonly appears in two scenarios: either you have a brand new repository that has been initialized with `git init` but has no commits yet, or the HEAD reference has become corrupted or points to a non-existent branch. In an empty repository, HEAD typically points to "refs/heads/main" or "refs/heads/master", but since no commits exist, that branch reference doesn't actually exist yet. Understanding this distinction is important because the solution depends on the root cause. For new repositories, you simply need to create your first commit. For corrupted repositories, you may need to repair the HEAD reference or recover from a remote.
First, verify whether your repository has any commits by checking if the HEAD reference points to an existing branch:
# Check what HEAD points to
cat .git/HEAD
# Try to list commits (will fail if none exist)
git rev-parse HEADIf you see "fatal: ambiguous argument 'HEAD'" or similar, the repository likely has no commits.
If the repository is empty, create your first commit to establish a valid HEAD:
# Create a file and make the first commit
echo "# Project" > README.md
git add README.md
git commit -m "Initial commit"Alternatively, create an empty commit without any files:
git commit --allow-empty -m "Initial commit"After this, HEAD will point to a valid commit and the error should be resolved.
If HEAD points to the wrong branch (e.g., "main" when your branch is "master"), fix it with:
# Check available branches
ls .git/refs/heads/
# Point HEAD to an existing branch
git symbolic-ref HEAD refs/heads/master
# Or for main branch:
git symbolic-ref HEAD refs/heads/mainThis command updates the symbolic reference without modifying any files.
If you have a remote with valid commits, fetch and reset to recover:
# Fetch all branches from remote
git fetch --all --prune
# Create local branch tracking the remote
git checkout -B main origin/main
# Or:
git checkout -B master origin/masterThis downloads the commit history and establishes a valid local branch.
If the repository is severely corrupted and you have a remote backup, the safest option is to clone fresh:
# Backup any local changes first
cp -r my-repo my-repo-backup
# Clone a fresh copy
git clone <remote-url> my-repo-fresh
# Copy over any uncommitted work from backupThis ensures you get a clean repository state from the remote.
### Understanding HEAD in Git
HEAD is stored in .git/HEAD and typically contains a symbolic reference like ref: refs/heads/main. When you check out a specific commit (detached HEAD state), it contains the commit SHA directly.
### CI/CD Pipeline Considerations
In CI environments like Jenkins or GitHub Actions, this error often occurs because:
- Shallow clones (--depth 1) may not include the referenced commit
- The checkout happens before HEAD is properly set
- Workspaces aren't fully cleaned between runs
Solutions for CI:
# GitHub Actions - ensure full history
- uses: actions/checkout@v4
with:
fetch-depth: 0### Bare Repositories
Bare repositories (created with git init --bare) will show this error until they receive their first push. This is normal and expected.
### Git Version Compatibility
If you see this error when interacting with remote repositories, ensure Git versions are compatible between your local machine and remote server. Significant version differences (e.g., 1.x vs 2.x) can cause reference handling issues.
kex_exchange_identification: Connection closed by remote host
Connection closed by remote host when connecting to Git server
fatal: unable to access: Proxy auto-configuration failed
How to fix 'Proxy auto-configuration failed' in Git
fatal: unable to access: Authentication failed (proxy requires basic auth)
How to fix 'Authentication failed (proxy requires basic auth)' in Git
fatal: unable to access: no_proxy configuration not working
How to fix 'no_proxy configuration not working' in Git
fatal: unable to read tree object in treeless clone
How to fix 'unable to read tree object in treeless clone' in Git