What causes "fatal: the request was too large; try breaking it up"?

Too many commits or changes bundled in a single push operation Large binary files or many files added in commits being pushed Git's http.postBuffer is too small for the transfer size

How to fix fatal: the request was too large; try breaking it up in Git

GitINTERMEDIATEMEDIUMUpdated Dec 6, 2025· 146 views

The 'request was too large' error occurs when Git attempts to transfer more data than the server or network can handle in a single HTTP request. This commonly happens when pushing large repositories, many commits, or files that exceed buffer limits.

Quick fix

Fixes fatal: the request was too large; try breaking it up

# Check how many commits are ahead of remote
git log origin/main..HEAD --oneline | wc -l

# Push commits in batches using specific commit SHAs
# First, find a commit roughly halfway through your unpushed commits
git log origin/main..HEAD --oneline

# Push up to a specific commit
git push origin <commit-sha>:main

# Repeat until all commits are pushed
git push origin main

Push commits in smaller batches
Increase Git's HTTP buffer size
Use SSH instead of HTTPS
Use Git LFS for large files

git — error

$# Check how many commits are ahead of remote
git log origin/main..HEAD --oneline | wc -l
# Push commits in batches using specific commit SHAs
# First, find a commit roughly halfway through your unpushed commits
git log origin/main..HEAD --oneline
# Push up to a specific commit
git push origin <commit-sha>:main
# Repeat until all commits are pushed
git push origin main
fatal: the request was too large; try breaking it up

What this error means

The "fatal: the request was too large; try breaking it up" error indicates that Git's HTTP transfer operation exceeded the maximum allowed request size. This limit can be imposed by Git itself, the remote server (GitHub, GitLab, Bitbucket), a reverse proxy (like nginx), or network infrastructure. When pushing over HTTPS, Git uses the HTTP protocol to send packed object data to the remote repository. If the combined size of all objects being pushed exceeds certain thresholds, the server or an intermediary will reject the request. The error message helpfully suggests the solution: break the push into smaller chunks. This error is different from large file rejection errors (like GitHub's 100MB limit per file). Instead, it relates to the total size of a single HTTP request, which can fail even if individual files are small but the cumulative data is too large.

Typical symptoms

git push fails with 'fatal: the request was too large; try breaking it up'
Push succeeds for small commits but fails for larger ones
Error occurs after accumulating many commits before pushing
Initial push of a large repository fails completely
Push works over SSH but fails over HTTPS
Error appears when pushing to self-hosted Git servers behind proxies
CI/CD pipelines fail during the push step with this error

Common causes

Too many commits or changes bundled in a single push operation
Large binary files or many files added in commits being pushed
Git's http.postBuffer is too small for the transfer size
Server-side request size limits (nginx client_max_body_size, Apache LimitRequestBody)
Reverse proxy or load balancer rejecting chunked transfer encoding
Corporate firewall or proxy imposing request size restrictions
Repository has grown very large over time with accumulated history

How to fix "fatal: the request was too large; try breaking it up"

1Push commits in smaller batches

The most direct solution is to push fewer commits at a time. If you have many unpushed commits, push them incrementally:

bash

# Check how many commits are ahead of remote
git log origin/main..HEAD --oneline | wc -l

# Push commits in batches using specific commit SHAs
# First, find a commit roughly halfway through your unpushed commits
git log origin/main..HEAD --oneline

# Push up to a specific commit
git push origin <commit-sha>:main

# Repeat until all commits are pushed
git push origin main

For example, if you have 100 unpushed commits:

bash

# Push first 25 commits
git push origin HEAD~75:main

# Push next 25
git push origin HEAD~50:main

# Push next 25
git push origin HEAD~25:main

# Push remaining commits
git push origin main

2Increase Git's HTTP buffer size

Increase the http.postBuffer to allow larger transfers. This sets how much data Git buffers before sending:

bash

# Increase buffer to 500 MB
git config --global http.postBuffer 524288000

# For very large repositories, try 1 GB
git config --global http.postBuffer 1048576000

Note: In Git 2.9 and newer, this setting has less effect as Git improved its HTTP handling. Try other solutions first if you have a modern Git version.

bash

# Check your Git version
git --version

# If older than 2.9, consider upgrading first

3Use SSH instead of HTTPS

SSH doesn't have the same HTTP request size limitations. Switch your remote URL to use SSH:

bash

# Check current remote URL
git remote -v

# Change from HTTPS to SSH (GitHub example)
git remote set-url origin git@github.com:username/repository.git

# For GitLab
git remote set-url origin git@gitlab.com:username/repository.git

# For Bitbucket
git remote set-url origin git@bitbucket.org:username/repository.git

# Verify the change
git remote -v

# Now try pushing
git push origin main

You'll need SSH keys set up:

bash

# Generate SSH key if needed
ssh-keygen -t ed25519 -C "your_email@example.com"

# Add to SSH agent
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

# Copy public key to add to your Git hosting service
cat ~/.ssh/id_ed25519.pub

4Use Git LFS for large files

If your repository contains large binary files, use Git Large File Storage (LFS) to handle them separately:

bash

# Install Git LFS
git lfs install

# Track large file types
git lfs track "*.zip"
git lfs track "*.tar.gz"
git lfs track "*.bin"
git lfs track "*.dll"
git lfs track "*.so"

# Add the .gitattributes file
git add .gitattributes
git commit -m "Configure Git LFS tracking"

# Migrate existing large files to LFS (if already committed)
git lfs migrate import --include="*.zip,*.tar.gz" --everything

# Force push after migration (careful!)
git push --force-with-lease origin main

LFS stores large files separately and only pushes pointers in regular Git operations, avoiding the request size issue.

5Perform a shallow clone and re-push

If pushing an existing large repository, create a fresh shallow clone and push that:

bash

# Clone with limited history
git clone --depth 1 https://github.com/username/repository.git repo-shallow
cd repo-shallow

# Add your new remote (if different)
git remote add target https://github.com/username/new-repository.git

# Push the shallow clone
git push target main

# If you need full history, fetch it incrementally
git fetch --deepen=100
git push target main
# Repeat until full history is transferred

This approach breaks the transfer into manageable chunks.

6Configure server-side limits (self-hosted servers)

If you control the Git server, increase the request size limits:

For nginx (reverse proxy):

nginx

# In nginx.conf or site configuration
server {
    # Allow unlimited request size
    client_max_body_size 0;

    # Or set a specific large limit
    # client_max_body_size 1024m;

    # Disable request buffering for streaming
    proxy_request_buffering off;

    # Increase timeouts for large transfers
    proxy_read_timeout 300;
    proxy_connect_timeout 300;
    proxy_send_timeout 300;
}

For Apache:

apache

# In httpd.conf or .htaccess
LimitRequestBody 0
TimeOut 300
ProxyTimeout 300

Restart the web server after making changes.

7Reduce repository size before pushing

If the repository contains unnecessary large files or history, clean it up:

bash

# Find large files in history
git rev-list --objects --all | \
  git cat-file --batch-check='%(objecttype) %(objectname) %(objectsize) %(rest)' | \
  sed -n 's/^blob //p' | \
  sort -rnk2 | \
  head -20

# Remove large files from history using git-filter-repo (recommended)
# Install: pip install git-filter-repo
git filter-repo --invert-paths --path path/to/large/file

# Or remove by size (removes files over 100MB from history)
git filter-repo --strip-blobs-bigger-than 100M

# Run garbage collection
git gc --aggressive --prune=now

# Force push the cleaned repository
git push --force-with-lease origin main

Warning: This rewrites history. Coordinate with your team before doing this.

8Check and bypass proxy issues

Corporate proxies or VPNs may impose their own limits. Test if the proxy is the issue:

bash

# Check if proxy is configured
git config --global --get http.proxy
git config --global --get https.proxy

# Temporarily bypass proxy (if allowed)
git config --global --unset http.proxy
git config --global --unset https.proxy

# Or set NO_PROXY for Git hosts
export no_proxy="github.com,gitlab.com,bitbucket.org"

# Try push again
git push origin main

# Re-enable proxy if needed
git config --global http.proxy http://proxy.company.com:8080

If bypassing the proxy works, contact your network administrator about increasing proxy limits for Git traffic.

Advanced notes

### Understanding HTTP Request Size Limits

Git's Smart HTTP protocol uses chunked transfer encoding for large transfers (>1MB). The request size can be limited at multiple points:

1. Git client: Controlled by http.postBuffer (default ~1MB)
2. Reverse proxy: nginx client_max_body_size, Apache LimitRequestBody
3. Git server: GitLab, Bitbucket Server, etc. have their own limits
4. Load balancers: AWS ALB, Azure Application Gateway, etc.
5. CDN/WAF: Cloudflare, AWS WAF, etc.

### Why SSH Doesn't Have This Problem

SSH uses a different transport mechanism that streams data rather than sending it in HTTP requests. There's no request body size concept - data flows through the encrypted SSH tunnel without the same buffering requirements.

### Git Protocol Version

Force a specific Git protocol version if you suspect protocol negotiation issues:

bash

# Use Git protocol version 2 (more efficient)
git config --global protocol.version 2

# Or fall back to version 1 if v2 causes issues
git config --global protocol.version 1

### CI/CD Pipeline Considerations

In CI/CD environments where you can't easily switch to SSH:

yaml

# GitHub Actions example with incremental push
- name: Push incrementally
  run: |
    commits=$(git rev-list origin/main..HEAD --count)
    if [ $commits -gt 50 ]; then
      # Push in batches of 50 commits
      for i in $(seq 50 50 $commits); do
        git push origin HEAD~$((commits-i)):main
      done
    fi
    git push origin main

### Monitoring Pack File Sizes

Check the size of objects being transferred:

bash

# See pack file that would be created
git rev-list --objects --all | git pack-objects --stdout > /dev/null

# Count objects and size
git count-objects -v

# Size of specific commits being pushed
git diff --stat origin/main..HEAD

### When All Else Fails

If you absolutely cannot push over HTTPS and SSH isn't available:

1. Create a bundle file: git bundle create repo.bundle --all
2. Transfer the bundle file manually (upload, email, etc.)
3. On the server: git clone repo.bundle repo-dir

This completely bypasses network size limits.

Frequently asked questions

What does "fatal: the request was too large; try breaking it up" mean?: The "fatal: the request was too large; try breaking it up" error indicates that Git's HTTP transfer operation exceeded the maximum allowed request size. This limit can be imposed by Git itself, the remote server (GitHub, GitLab, Bitbucket), a reverse proxy (like nginx), or network infrastructure. When pushing over HTTPS, Git uses the HTTP protocol to send packed object data to the remote repository.
How do I fix "fatal: the request was too large; try breaking it up"?: The 'request was too large' error occurs when Git attempts to transfer more data than the server or network can handle in a single HTTP request. This commonly happens when pushing large repositories, many commits, or files that exceed buffer limits.
What causes "fatal: the request was too large; try breaking it up"?: Too many commits or changes bundled in a single push operation Large binary files or many files added in commits being pushed Git's http.postBuffer is too small for the transfer size
Is the "fatal: the request was too large; try breaking it up" error serious?: It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading

📚Git Official Documentation
📖
Git Configuration - http.postBuffer - Git SCM(Official Docs)
📖
RPC failures and http.postBuffer - Azure DevOps(Official Docs)
💬
Git fails when pushing commit to GitHub - Stack Overflow(Stack Overflow)
📖
Git Push Fails - fatal: The remote end hung up unexpectedly - Atlassian(Official Docs)
📖
Git push fails - client intended to send too large chunked body - Atlassian(Official Docs)
📖
Git LFS Documentation - Git SCM(Official Docs)

How to fix fatal: the request was too large; try breaking it up in Git

Quick fix

What this error means

Typical symptoms

Common causes

How to fix "fatal: the request was too large; try breaking it up"

Advanced notes

Frequently asked questions

Related errors

Official resources & further reading