The 'RPC failed; HTTP 502 Bad Gateway' error occurs during Git push, pull, or clone operations when a proxy server or load balancer cannot communicate with the upstream Git server. This is typically a server-side issue but can sometimes be resolved by adjusting Git configuration or using SSH instead of HTTPS.
The "RPC failed; HTTP 502 Bad Gateway" error indicates that Git's HTTP request reached a proxy server or load balancer, but that intermediary could not get a valid response from the actual Git server behind it. HTTP 502 is a server-side error code meaning the gateway or proxy received an invalid or no response from the upstream server. In most Git hosting setups (GitHub, GitLab, Bitbucket, or self-hosted), there's typically a reverse proxy (like nginx or Apache) in front of the Git application server. When this proxy cannot communicate with the backend Git service, it returns a 502 error. This error commonly occurs during push operations with large repositories, when the backend server is overloaded or experiencing issues, or when there are timeout or authentication problems between the proxy and the application server. Unlike client-side errors, 502 errors often indicate that the problem is on the server side, though certain client-side configurations can help work around temporary issues.
Since HTTP 502 is often a temporary server-side issue, the first step is to wait a few minutes and try again:
# Wait 2-5 minutes, then retry your command
git push origin main
# Check if the remote is accessible
git ls-remote originIf the error persists after several retries over 10-15 minutes, proceed to the next steps.
Before troubleshooting locally, verify the Git server is operational:
- GitHub: https://www.githubstatus.com/
- GitLab: https://status.gitlab.com/
- Bitbucket: https://status.bitbucket.org/
- Azure DevOps: https://status.dev.azure.com/
For self-hosted instances, contact your system administrator or check server logs.
You can also test connectivity:
# Test HTTPS connectivity
curl -I https://github.com
curl -I https://gitlab.com
# For self-hosted GitLab, check if web interface loads
curl -I https://your-gitlab-server.comLarge pushes can fail if Git's HTTP buffer is too small. Increase it to allow larger transfers:
# Increase buffer to 500 MB (for most cases)
git config --global http.postBuffer 524288000
# For very large repositories, try 1 GB
git config --global http.postBuffer 1048576000
# You can also set it locally for just this repository
git config --local http.postBuffer 524288000Then retry your push operation. Note that this increases memory usage during Git HTTP operations.
If you're pushing many files or large commits, break them into smaller batches:
# First, see how many commits you're trying to push
git log origin/main..HEAD --oneline
# Push commits one at a time
git push origin HEAD~5:main # Push all but last 5 commits
git push origin HEAD~4:main # Push one more
git push origin HEAD~3:main
# Continue until all commits are pushed
git push origin main
# Or if you have specific large files, use .gitignore
# and push them separately using Git LFSFor initial large pushes, consider adding files in smaller commits:
# Stage and commit files in batches
git add src/
git commit -m "Add source files"
git push
git add assets/
git commit -m "Add assets"
git pushSSH connections bypass HTTP proxies entirely and often work when HTTPS fails:
# Check your current remote URL
git remote -v
# Change from HTTPS to SSH
# GitHub:
git remote set-url origin [email protected]:username/repo.git
# GitLab:
git remote set-url origin [email protected]:username/repo.git
# Bitbucket:
git remote set-url origin [email protected]:username/repo.git
# Verify the change
git remote -vIf you haven't set up SSH keys:
# Generate SSH key
ssh-keygen -t ed25519 -C "[email protected]"
# Start ssh-agent
eval "$(ssh-agent -s)"
# Add your key
ssh-add ~/.ssh/id_ed25519
# Copy public key to add to GitHub/GitLab/Bitbucket
cat ~/.ssh/id_ed25519.pubAdd the public key to your Git hosting provider's SSH keys settings.
Proxy configurations can interfere with Git HTTP connections:
# Check if proxy is configured in Git
git config --global --get http.proxy
git config --global --get https.proxy
# Check environment variables
echo $http_proxy
echo $https_proxy
echo $HTTP_PROXY
echo $HTTPS_PROXY
# Remove Git proxy settings if set
git config --global --unset http.proxy
git config --global --unset https.proxy
# Temporarily unset environment variables for testing
unset http_proxy
unset https_proxy
unset HTTP_PROXY
unset HTTPS_PROXY
# Now retry your Git operation
git push origin mainIf you need the proxy for other operations, you can set a proxy bypass for your Git server:
# On Linux/macOS
export no_proxy="github.com,gitlab.com"
# Or in Git config
git config --global http.https://github.com.proxy ""Compression can sometimes cause issues with large transfers. Try disabling it:
# Disable compression
git config --global core.compression 0
# Also try increasing the request buffer
git config --global http.maxRequestBuffer 100M
# Retry your push
git push origin main
# After successful push, you can re-enable compression
git config --global core.compression -1If the repository is corrupted or the issue persists, clone a fresh copy:
# Backup your current work
cp -r my-repo my-repo-backup
# Clone fresh using SSH (recommended)
git clone [email protected]:username/repo.git my-repo-fresh
# Copy your changes to the fresh clone
cp -r my-repo-backup/path/to/changed/files my-repo-fresh/
# Commit and push from fresh clone
cd my-repo-fresh
git add .
git commit -m "Add changes from backup"
git push origin main### Server-Side Fixes for Self-Hosted GitLab
If you're administering a self-hosted GitLab instance, the 502 error often relates to timeout settings:
Edit /etc/gitlab/gitlab.rb:
# Increase Puma/Unicorn worker timeout (default is 60 seconds)
puma['worker_timeout'] = 120
# Or for older GitLab versions using Unicorn
unicorn['worker_timeout'] = 120
# Increase nginx proxy timeouts
nginx['proxy_read_timeout'] = 300
nginx['proxy_connect_timeout'] = 300Then reconfigure:
sudo gitlab-ctl reconfigure
sudo gitlab-ctl restart### Apache Reverse Proxy Configuration
If using Apache as a reverse proxy:
<Location />
ProxyPass http://localhost:3000/
ProxyPassReverse http://localhost:3000/
ProxyTimeout 300
</Location>### nginx Reverse Proxy Configuration
For nginx reverse proxy:
location / {
proxy_pass http://git-backend;
proxy_read_timeout 300;
proxy_connect_timeout 300;
proxy_send_timeout 300;
client_max_body_size 0; # Allow unlimited upload size
}### Understanding curl Error Codes
The full error often includes "curl 22" which means:
- curl error 22: CURLE_HTTP_RETURNED_ERROR - HTTP response code indicated an error (4xx or 5xx)
- Combined with 502, this confirms the server returned a Bad Gateway response
### Cloud Platform Billing Issues
On Google Cloud Platform, AWS, or Azure, HTTP 502 errors can occur when:
- Your billing account is suspended
- You've exceeded quota limits
- The service is disabled in your project
Check your cloud console billing section and service quotas if using cloud-hosted Git services.
### Large File Storage (Git LFS)
For repositories with large files, use Git LFS to avoid HTTP buffer issues:
# Install Git LFS
git lfs install
# Track large file types
git lfs track "*.psd"
git lfs track "*.zip"
git lfs track "*.bin"
# Commit the .gitattributes file
git add .gitattributes
git commit -m "Configure Git LFS"
# Now large files will be handled separately
git push origin main### Debugging HTTP Issues
Enable verbose output to diagnose the exact failure point:
GIT_TRACE=1 GIT_TRACE_PACKET=1 GIT_CURL_VERBOSE=1 git push origin main 2>&1 | tee git-debug.logThis will show exactly where the HTTP connection fails.
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