This Git error occurs when you try to clone, verify, or unbundle a file that Git doesn't recognize as a valid bundle format. The file may be corrupted, not actually a Git bundle, or created with an incompatible Git version. Verify the file format and recreate the bundle if needed.
The "does not look like a v2 or v3 bundle file" error occurs when Git attempts to read a file as a bundle but cannot find the expected bundle format signature. Git bundles are self-contained archives that include both refs (branch/tag references) and Git objects (commits, trees, blobs) in a specific format. A valid Git bundle starts with a signature line: `# v2 git bundle` for version 2 or `# v3 git bundle` for version 3. When Git reads a file and doesn't find this signature at the beginning, it reports this error. The v2 format works with SHA-1 repositories, while v3 supports additional capabilities like SHA-256. This error typically indicates one of several problems: - The file was corrupted during transfer or storage - The file is not actually a Git bundle (it might be a tar archive, a regular repository backup, or an unrelated file) - The download was incomplete or interrupted - The file was created with a very old or incompatible Git version - Someone renamed or mislabeled a non-bundle file with a .bundle extension
First, check what type of file you actually have:
# Check the file type
file your-file.bundle
# Look at the first few bytes to see the signature
head -c 50 your-file.bundle
# For a valid bundle, you should see:
# # v2 git bundle
# or
# # v3 git bundleIf you see something like "gzip compressed data" or "tar archive", the file is not a Git bundle but a compressed archive that might contain one.
If the file is actually a tar or zip archive (common with GitLab backups), extract it first:
# For tar.gz files
tar -xzf your-file.bundle -C ./extracted
# For tar files
tar -xf your-file.bundle -C ./extracted
# For zip files
unzip your-file.bundle -d ./extracted
# Look for the actual bundle or bare repository inside
ls -la ./extractedAfter extraction, look for either a .bundle file or a bare Git repository (containing HEAD, objects/, refs/ directories).
If the extracted content is a bare Git repository rather than a bundle:
# Check if it looks like a bare repository
ls extracted/
# Should show: HEAD config objects refs ...
# Clone from the bare repository
git clone ./extracted my-repo
# Or initialize and fetch
git init my-repo
cd my-repo
git remote add origin ../extracted
git fetch origin
git checkout mainGitLab backups often contain bare repositories inside tar archives labeled as bundles.
If you have what appears to be a real bundle, verify its integrity:
# Verify the bundle
git bundle verify your-file.bundle
# If verification fails, check file size
ls -lh your-file.bundle
# Compare with expected size if known
# A very small file (< 1KB) might indicate incomplete download
# Check for any checksum or hash if provided
sha256sum your-file.bundleIf the bundle verifies successfully but still fails on clone, try using git bundle unbundle in an existing repository.
If the file was transferred over a network, it may have been corrupted:
# If downloaded via curl/wget, use binary mode explicitly
curl -L -o repo.bundle https://example.com/repo.bundle
# For SCP, ensure binary transfer
scp user@host:/path/to/repo.bundle ./repo.bundle
# For FTP, use binary mode
ftp> binary
ftp> get repo.bundle
# After re-downloading, verify the signature again
head -c 50 repo.bundleSome transfer methods can corrupt binary files by applying text transformations (like CRLF conversion).
If you have access to the original repository, create a fresh bundle:
# On the source machine with the repository
cd /path/to/repository
# Create a complete bundle with all refs
git bundle create repo.bundle --all
# Or bundle specific branches
git bundle create repo.bundle main develop
# Verify the new bundle
git bundle verify repo.bundle
# The output should show:
# The bundle contains X refs, ...
# repo.bundle is okayTransfer the new bundle and try again on the destination machine.
GitLab backup files require special handling. The repo.bundle in GitLab backups is often inside nested tar archives:
# Extract the main backup archive
tar -xf gitlab_backup.tar
# Navigate to the repositories directory
cd repositories
# Find bundle files
find . -name "*.bundle"
# GitLab stores repositories in a specific structure
# The path is usually: @hashed/XX/YY/HASH.bundle
# Extract and clone the specific repository bundle
git clone ./path/to/project.bundle restored-projectIf the bundle file still fails, check if it's actually a bare repository packed in tar format and follow step 3.
### Understanding Git Bundle Format
Git bundles are portable, self-contained archives of repository data. The format consists of:
1. Signature line: # v2 git bundle or # v3 git bundle
2. Prerequisites (optional): Objects the recipient must already have
3. References: Branch and tag refs being bundled
4. Pack data: Compressed Git objects
You can inspect a bundle's structure:
# View bundle contents without extracting
git bundle list-heads repo.bundle
# Show prerequisites (commits the recipient needs)
git bundle verify repo.bundle### V2 vs V3 Bundle Format
| Feature | V2 | V3 |
|---------|----|----|
| Hash Algorithm | SHA-1 only | SHA-1 or SHA-256 |
| Capabilities | None | Extensible |
| Git Version | All versions | Git 2.39+ |
V3 bundles may not work with older Git versions. Check your Git version:
git --version### Creating Bundles for Offline Transfer
When creating bundles for transfer to air-gapped systems:
# Full repository bundle (all history, all branches)
git bundle create full-repo.bundle --all
# Incremental bundle (changes since a known commit)
git bundle create incremental.bundle origin/main..main
# Bundle with tags
git bundle create with-tags.bundle --all --tags### Recovering Data from Corrupted Bundles
If a bundle is partially corrupted but was once valid:
# Try extracting what you can
git init recovery
cd recovery
# Attempt to fetch from the bundle
git fetch ../corrupted.bundle '*:*' 2>&1 | tee fetch.log
# Check what was recovered
git branch -a
git log --oneline --all
# Run fsck to identify issues
git fsck --full### Alternative: Using git-archive
If bundles aren't working for your use case, consider git archive:
# Create a tar archive of a specific commit (without history)
git archive --format=tar.gz -o snapshot.tar.gz HEAD
# This creates a source snapshot, not a full repositoryNote: git archive only exports file contents, not Git history or refs.
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