Git reports 'fatal: bad object' when it cannot find or read a referenced object in the repository database. This typically occurs during git gc, status, or other operations when a commit, tree, or blob is missing or corrupted due to incomplete operations, shallow clones, or filesystem issues.
The "fatal: bad object" error indicates Git cannot locate or read an object (commit, tree, blob, or tag) that is referenced somewhere in your repository. Every piece of data in Git is stored as an object identified by a 40-character SHA-1 hash. When Git needs to access an object but finds it missing, corrupted, or unreadable, it throws this fatal error. This error commonly appears during garbage collection (`git gc`), but can occur with any Git command that needs to traverse the object graph. The referenced object hash in the error message (e.g., `abc1234`) tells you exactly which object Git cannot find. Common scenarios that trigger this error include: - Running `git gc` when remote tracking branches point to deleted or unavailable objects - Shallow clones missing referenced parent commits - Repository corruption from interrupted operations or disk issues - Cloud sync services (Dropbox, iCloud, OneDrive) causing partial .git folder syncs - Stale references to objects that were pruned or never fetched
First, determine which reference is causing the issue:
# Run fsck to find all bad objects
git fsck --full
# Check what refs exist
git show-ref
# Look at the specific error - if it mentions a path like
# refs/remotes/origin/HEAD, check that file:
cat .git/refs/remotes/origin/HEADNote the object hash and reference path from the error message - this guides which fix to apply.
If the error mentions refs/remotes/origin/HEAD, the remote's default branch may have been renamed or deleted:
# Auto-detect and update the remote HEAD
git remote set-head origin --auto
# If that fails, manually set it to the correct branch
git remote set-head origin main
# Prune stale remote-tracking references
git remote prune origin
# Verify the fix
git gcThis is the most common cause of "bad object" errors during git gc.
If a specific reference file is corrupted, you can remove it:
# First, check what the reference contains
cat .git/refs/remotes/origin/HEAD
# If it shows an invalid hash (all zeros, truncated, or garbled):
# Delete the corrupted reference
git update-ref -d refs/remotes/origin/HEAD
# For other corrupted refs, use the same pattern:
git update-ref -d "<corrupted-ref-path>"
# Then verify and fetch fresh data
git fetch origin
git gcYou can also manually delete the file: rm .git/refs/remotes/origin/HEAD
If objects are missing (common with shallow clones), fetch them:
# Fetch all objects from all remotes
git fetch --all
# For shallow clones, unshallow to get full history
git fetch --unshallow
# Fetch with full object download
git fetch --refetch
# If specific branches are problematic:
git fetch origin main:refs/remotes/origin/mainAfter fetching, try your original command again.
Git's reflog may contain references to the missing objects:
# View reflog entries
git reflog
# Check all reflogs for the missing hash
git reflog --all | grep <partial-hash>
# If found, the object still exists - create a reference to prevent pruning
git branch recovered-<hash> <full-hash>Objects referenced by reflog are protected from garbage collection.
If the error occurs during gc with pack file issues:
# Unpack all pack files (creates loose objects)
git unpack-objects < .git/objects/pack/*.pack
# Remove old pack files
rm .git/objects/pack/*
# Repack the repository
git repack -a -d
# Run gc again
git gcWarning: This can be slow for large repositories.
If corruption is extensive, clone a fresh copy:
# Clone to a new directory
git clone <remote-url> repo-fresh
# If you have uncommitted changes, copy them over
# From the corrupted repo:
rsync -av --exclude='.git' ./ ../repo-fresh/
# Or on Windows:
xcopy /E /I /EXCLUDE:.git . ..\repo-fresh
# Switch to fresh clone
cd ../repo-fresh
git statusThis preserves your working directory while replacing corrupted Git data.
### Understanding Git Object Types
Git stores four types of objects:
- Blob: File contents (the actual data)
- Tree: Directory structure pointing to blobs and other trees
- Commit: Snapshot metadata with pointers to tree and parent commits
- Tag: Named reference to a specific object (usually a commit)
When you see "bad object <hash>", Git is looking for one of these objects but cannot find or read it.
### Shallow Clones and Bad Objects
Shallow clones (git clone --depth N) intentionally omit older objects to save space and time. This can cause "bad object" errors when:
# Check if your repository is shallow
git rev-parse --is-shallow-repository
# View the shallow boundary
cat .git/shallowOperations that need historical data (like cherry-picking old commits or running git gc) may fail. Use git fetch --unshallow to convert to a full clone.
### Preventing Bad Object Errors
Avoid cloud sync on .git folders:
# Exclude .git from Dropbox/iCloud/OneDrive
# Add to your sync service's exclusion list
echo ".git" >> .dropboxignore # DropboxConfigure gc safety settings:
# Prevent gc from running automatically during operations
git config --global gc.auto 0
# When running gc manually, be cautious with prune
git gc --prune=2.weeks.ago # Default, keeps recent unreachable objects### CI/CD Best Practices
In CI/CD environments with cached repositories:
# Clean stale references before operations
git remote prune origin
# Fetch with cleanup
git fetch --prune --prune-tags
# For long-lived caches, run periodic maintenance
git maintenance run --auto### Diagnosing with git fsck
Get detailed information about repository health:
# Full integrity check with verbose output
git fsck --full --verbose
# Show connectivity issues
git fsck --connectivity-only
# Find unreachable objects that might help recovery
git fsck --unreachable --no-reflogs### Recovery with git-repair
For complex corruption, use the git-repair tool:
# Install (Debian/Ubuntu)
sudo apt install git-repair
# Install (macOS)
brew install git-repair
# Run automated repair
git-repair
# Force repair even with data loss risk
git-repair --forcekex_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