How to fix error: unable to read alternates file in Git

First, examine what alternate object stores your repository is configured to use:

# View the alternates file
cat .git/objects/info/alternates

This file contains paths to other Git object directories, one per line. Common examples:

/home/shared/repo.git/objects
../reference-repo/.git/objects

Verify each path exists:

# Check if the path exists
ls -la /path/from/alternates/file

If any path doesn't exist or is inaccessible, that's your problem.

If you no longer need object sharing or the reference repository is gone, simply remove the alternates file:

# Remove the alternates file
rm .git/objects/info/alternates

Important: After removing the alternates file, your repository may be missing objects. Run a verification:

# Check for missing objects
git fsck --full

If objects are missing, you'll need to either:
1. Fetch them from the remote
2. Restore from a backup
3. Repack the repository (see next step)

If your repository was dependent on the alternate object store, you can fetch missing objects from the remote and repack:

# First, try to fetch all objects from remote
git fetch --all

# Repack all objects into the local repository
git repack -a -d

# Remove the alternates file after repacking
rm -f .git/objects/info/alternates

# Verify the repository is complete
git fsck --full

The git repack -a -d command:
- -a - Repack all objects into new pack files
- -d - Remove redundant loose objects

This creates a self-contained repository that no longer depends on alternates.

If starting fresh is an option, clone with the --dissociate flag to get the benefits of --reference without the long-term dependency:

# Clone using reference but immediately dissociate
git clone --reference /path/to/reference/repo --dissociate <remote-url>

The --dissociate flag tells Git to:
1. Use the reference repository during initial clone (faster)
2. Immediately copy any borrowed objects into the new clone
3. Remove the alternates reference after cloning

This gives you the speed benefit of a reference clone without creating a dependency on the reference repository existing forever.

For existing repository:

# If you want to dissociate an existing clone
git repack -a -d
rm .git/objects/info/alternates

If the reference repository still exists but at a different location, update the alternates file:

# Edit the alternates file
nano .git/objects/info/alternates

# Or replace the path directly
echo "/new/path/to/reference/.git/objects" > .git/objects/info/alternates

Path format guidelines:
- Use absolute paths when possible
- On Windows, use forward slashes: C:/Users/name/repo/.git/objects
- Each path should point to a .git/objects directory
- One path per line, no trailing whitespace

Verify the new path works:

# Test if Git can read objects
git fsck --full

If the reference repository exists but Git cannot read it, check permissions:

# Check permissions on the reference repository
ls -la /path/to/reference/.git/objects

# The objects directory and its contents need read access
# For a shared reference repository, set group read permissions:
chmod -R g+rX /path/to/reference/.git/objects

Common permission scenarios:
- User running Git changed (different account)
- CI/CD runner user differs from setup user
- Docker container running as different UID

For shared team reference repositories:

# Make the reference repository readable by all
chmod -R a+rX /path/to/reference/.git

In Docker or containerized environments, alternates often break because paths inside the container differ from paths on the host:

Problem scenario:

# Host created a reference clone at /home/user/reference
# Container sees the world differently
docker run -v /home/user/reference:/mnt/reference ...
# But alternates file still points to /home/user/reference

Solutions:

Option 1: Mount reference at the same path

docker run -v /home/user/reference:/home/user/reference ...

Option 2: Dissociate before containerizing

# On host, before building container
git repack -a -d
rm .git/objects/info/alternates

Option 3: Update alternates for container paths

# Inside container
echo "/mnt/reference/.git/objects" > .git/objects/info/alternates

For CI/CD pipelines: Always use --dissociate when cloning with --reference to avoid this class of problems entirely.