How to fix fatal: protocol error: bad pack header in Git

GitINTERMEDIATEMEDIUMUpdated Dec 6, 2025· 206 views

The 'fatal: protocol error: bad pack header' error occurs when Git fails to properly receive or interpret packfile data during network operations like clone, fetch, or pull. This is typically caused by memory constraints on the server or corrupted repository data.

Quick fix

Fixes fatal: protocol error: bad pack header

git config --global pack.windowMemory "100m"
git config --global pack.packSizeLimit "100m"
git config --global pack.threads "1"
  1. Configure Git pack memory limits
  2. Prune stale remote references
  3. Increase HTTP buffer size (for HTTP/HTTPS remotes)
  4. Reset remote configuration (for corrupted local state)
git — error
git config --global pack.windowMemory "100m"
git config --global pack.packSizeLimit "100m"
git config --global pack.threads "1"
fatal: protocol error: bad pack header

What this error means

This error indicates that Git's pack protocol communication has failed during a network operation. When Git transfers objects between repositories (during clone, fetch, push, or pull), it uses an efficient binary format called "packfiles" to bundle multiple objects together. The pack header contains metadata about the packfile contents, including a signature, version number, and object count. When Git receives data that doesn't match the expected pack header format, it raises this error. This typically happens in one of three scenarios: the server ran out of memory while generating the packfile, the network connection was interrupted or corrupted during transfer, or the repository itself has become corrupted. The error is more common with large repositories that contain many objects or large files.

Typical symptoms

  • Git clone fails with 'fatal: protocol error: bad pack header'
  • Git pull or fetch operations fail unexpectedly
  • Error occurs more frequently with large repositories
  • Operations may work intermittently or fail consistently
  • CI/CD pipelines fail during repository checkout
  • Error appears after remote branches were deleted
  • Operations succeed from some machines but fail from others

Common causes

  1. Server running out of memory during pack generation (most common)
  2. Limited virtual memory or ulimit restrictions on the server
  3. Repository with large files causing memory-intensive repacking
  4. Corrupted repository data from interrupted operations
  5. Stale local references pointing to deleted remote branches
  6. Network interruption or packet corruption during transfer
  7. Git version incompatibility or bugs (fixed in Git 2.20+)
  8. Too many open files error on the server

How to fix "fatal: protocol error: bad pack header"

1Configure Git pack memory limits

The most common fix is to limit the memory Git uses during pack operations. Run these commands to set global limits:

bash
git config --global pack.windowMemory "100m"
git config --global pack.packSizeLimit "100m"
git config --global pack.threads "1"

The pack.threads "1" setting is often the key fix - it prevents Git from using multiple threads during packing, which reduces memory usage significantly. If you're a server administrator, run these commands on the server as the SSH user that handles Git connections.

2Prune stale remote references

If remote branches were deleted, your local repository may have stale references causing this error. Prune them:

bash
git remote prune origin

To make pruning automatic on all future fetches:

bash
git config --global fetch.prune true

This ensures that local references to deleted remote branches are cleaned up automatically.

3Increase HTTP buffer size (for HTTP/HTTPS remotes)

If you're using HTTP/HTTPS to access the repository, increase the post buffer size:

bash
git config --global http.postBuffer 524288000

This sets the buffer to 500MB, which helps with large repository transfers over HTTP.

4Reset remote configuration (for corrupted local state)

If your local repository has corrupted remote state, you can reset it while preserving your configuration:

bash
cp .git/config .git/config.backup
git remote remove origin
mv .git/config.backup .git/config
git fetch

This removes and re-adds the remote connection, clearing any corrupted cached data while preserving your remote URL and other settings.

5Perform a fresh clone

If other methods fail, a fresh clone often resolves the issue:

bash
cd ..
mv my-repo my-repo-backup
git clone <repository-url>

If you have local changes or branches, you can copy them from your backup after the fresh clone.

6Run garbage collection on the server

If you have access to the server hosting the repository, running garbage collection can fix pack-related issues:

bash
# On the server, in the bare repository directory
git gc --aggressive

This repacks all objects and cleans up any corrupt or orphaned data. After running gc, try your operation again from the client.

7Upgrade Git to version 2.20 or later

A bug related to mutex initialization in pack-objects was fixed in Git 2.20 (released Q4 2018). Check your Git version:

bash
git --version

If you're running an older version, upgrade Git:

bash
# Ubuntu/Debian
sudo add-apt-repository ppa:git-core/ppa
sudo apt update
sudo apt install git

# macOS with Homebrew
brew upgrade git

# Windows
# Download the latest installer from https://git-scm.com/download/win

Advanced notes

### Understanding Git Pack Protocol

Git's pack protocol is designed for efficient object transfer. When you run git fetch or git clone, the server runs git-upload-pack to generate a packfile containing the requested objects. The pack header is a 12-byte structure containing:
- 4-byte signature: "PACK"
- 4-byte version number (usually 2)
- 4-byte object count

If any of these don't match expectations, you'll see the "bad pack header" error.

### Memory Considerations

Pack generation is memory-intensive because Git needs to:
1. Find all objects to send
2. Compute deltas between similar objects
3. Compress and write the packfile

For large repositories, this can require several gigabytes of RAM. The pack.windowMemory and pack.packSizeLimit settings help by limiting how much data Git tries to process at once.

### Server-Side Troubleshooting

If you're a server administrator seeing this error:
1. Check server memory usage during Git operations
2. Review ulimit settings for the Git user
3. Consider increasing swap space as a temporary measure
4. For very large repos, consider using Git LFS for large files
5. Monitor with: git --bare fsck-objects --full to check repository integrity

### CI/CD Environments

In CI/CD environments with limited resources, add these settings to your pipeline configuration:

yaml
# Example for GitHub Actions
- name: Configure Git
  run: |
    git config --global pack.windowMemory "100m"
    git config --global pack.packSizeLimit "100m"
    git config --global pack.threads "1"

Frequently asked questions

What does "fatal: protocol error: bad pack header" mean?
This error indicates that Git's pack protocol communication has failed during a network operation. When Git transfers objects between repositories (during clone, fetch, push, or pull), it uses an efficient binary format called "packfiles" to bundle multiple objects together. The pack header contains metadata about the packfile contents, including a signature, version number, and object count.
How do I fix "fatal: protocol error: bad pack header"?
The 'fatal: protocol error: bad pack header' error occurs when Git fails to properly receive or interpret packfile data during network operations like clone, fetch, or pull. This is typically caused by memory constraints on the server or corrupted repository data.
What causes "fatal: protocol error: bad pack header"?
Server running out of memory during pack generation (most common) Limited virtual memory or ulimit restrictions on the server Repository with large files causing memory-intensive repacking
Is the "fatal: protocol error: bad pack header" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading