The 'RPC failed; HTTP 503 Service Unavailable' error occurs when Git cannot complete an operation because the remote server (GitHub, GitLab, Bitbucket, etc.) is temporarily unavailable or overloaded. This is typically a server-side issue that resolves itself, but there are steps you can take to work around it.
The "RPC failed; HTTP 503 Service Unavailable" error indicates that the remote Git server returned an HTTP 503 status code during a Git operation (clone, push, pull, or fetch). RPC (Remote Procedure Call) is the mechanism Git uses to communicate with remote servers over HTTP/HTTPS. HTTP 503 is a server-side error code meaning "Service Unavailable." This typically occurs when: - The server is temporarily overloaded with requests - The server is undergoing maintenance - A backend service the Git server depends on is down - Rate limiting has been applied to your requests - The server is experiencing technical difficulties Unlike client-side errors (4xx codes), a 503 error is not caused by anything wrong with your local Git configuration or credentials. The server is explicitly telling Git that it cannot handle the request at this time.
First, verify if the Git hosting service is experiencing issues:
GitHub:
- Status page: https://www.githubstatus.com/
- Twitter: https://twitter.com/githubstatus
GitLab:
- Status page: https://status.gitlab.com/
Bitbucket:
- Status page: https://bitbucket.status.atlassian.com/
Azure DevOps:
- Status page: https://status.dev.azure.com/
If the status page shows an incident, wait for the service to be restored. You can subscribe to status updates to be notified when the issue is resolved.
HTTP 503 errors are usually temporary. Wait a few minutes and try again:
# Wait 2-5 minutes, then retry your command
git push origin main
# Or for fetch/pull
git fetch originIf you're running automated scripts or CI/CD pipelines, implement retry logic with exponential backoff:
# Simple bash retry loop
for i in {1..5}; do
git push origin main && break
echo "Attempt $i failed, retrying in $((i * 30)) seconds..."
sleep $((i * 30))
doneIf HTTPS is failing due to server issues, SSH connections might still work as they often use different infrastructure:
# Change remote URL from HTTPS to SSH
git remote set-url origin [email protected]:username/repo.git
# Verify the change
git remote -v
# Now try your operation
git push origin mainFor GitLab:
git remote set-url origin [email protected]:username/repo.gitFor Bitbucket:
git remote set-url origin [email protected]:username/repo.gitNote: You'll need SSH keys set up for this to work. See the Git documentation for SSH key setup.
Some Git services return 503 errors when you've hit rate limits. Check if you're being rate limited:
For GitHub:
# Check your rate limit status (requires authentication)
curl -H "Authorization: token YOUR_TOKEN" https://api.github.com/rate_limitIf you're hitting rate limits:
- Reduce the frequency of automated operations
- Use authenticated requests (they have higher limits)
- Implement caching for frequently accessed data
- Consider using GitHub Apps for higher rate limits
For CI/CD systems:
- Ensure you're using service accounts with appropriate rate limits
- Cache dependencies and repositories between builds
- Use shallow clones to reduce data transfer
If you're cloning or fetching large repositories, the server might time out. Try reducing the data transfer:
# Use shallow clone with limited history
git clone --depth 1 https://github.com/username/repo.git
# For existing repos, fetch with depth limit
git fetch --depth 1 origin main
# Use single branch clone
git clone --single-branch --branch main https://github.com/username/repo.gitFor pushing large changes:
# Push in smaller batches
git push origin main~10:main
git push origin main~5:main
git push origin mainNetwork issues between you and the server can sometimes manifest as 503 errors:
# Test basic connectivity
ping github.com
curl -I https://github.com
# Check if a proxy is configured that might be failing
git config --global --get http.proxy
git config --global --get https.proxy
# Temporarily unset proxy to test direct connection
git config --global --unset http.proxy
git config --global --unset https.proxyIf you're behind a corporate proxy or firewall, it might be blocking or rate-limiting Git traffic. Contact your network administrator.
If you're using a self-hosted Git server (GitLab, Gitea, Gogs, etc.):
# Check server logs
sudo journalctl -u gitlab-runsvdir -f # For GitLab
sudo journalctl -u gitea -f # For Gitea
# Check system resources
top -b -n 1 | head -20
df -h # Check disk space
free -m # Check memory
# Restart the Git service if needed
sudo gitlab-ctl restart # For GitLab
sudo systemctl restart gitea # For GiteaCommon issues with self-hosted servers:
- Disk space full (especially for Git objects)
- Memory exhaustion
- Database connection issues
- Too many concurrent connections
If one remote is unavailable, you might be able to push to a mirror:
# Add a secondary remote as backup
git remote add backup [email protected]:username/repo.git
# Push to backup when primary is down
git push backup main
# Later, sync the mirrors when primary is back up
git push origin mainFor read operations, you can also clone from mirrors:
# Many popular repositories have mirrors
# Check if a mirror exists for the repository you need### Understanding 503 Errors in Distributed Systems
A 503 error from a Git server typically indicates the server is intentionally rejecting requests to protect itself. This is often a circuit breaker pattern in action - when a service becomes overloaded, it temporarily rejects new requests to prevent complete failure.
### GitHub-Specific Behavior
GitHub may return 503 errors during:
- High-traffic events (major open-source releases, popular projects)
- DDoS mitigation
- Deployment of new infrastructure
- Database maintenance windows
GitHub's smart HTTP protocol can sometimes trigger 503s during large operations even when the web interface works fine.
### CI/CD Pipeline Considerations
For CI/CD systems experiencing 503 errors:
# GitLab CI example with retry
job:
script:
- git push origin main
retry:
max: 3
when:
- runner_system_failure
- stuck_or_timeout_failure
# GitHub Actions example
- name: Push changes
run: |
for i in 1 2 3 4 5; do
git push origin main && break
sleep $((i * 60))
done### HTTP Retry-After Header
Some servers include a Retry-After header in 503 responses indicating when to retry. Check verbose output:
GIT_CURL_VERBOSE=1 git push origin main 2>&1 | grep -i retry### Graceful Degradation Strategies
For production systems:
1. Implement circuit breakers in your Git automation
2. Set up repository mirroring to multiple providers
3. Cache Git objects locally using Git's partial clone feature
4. Use Git bundles for offline backup
# Create a bundle backup
git bundle create repo-backup.bundle --all
# Restore from bundle if needed
git clone repo-backup.bundle restored-repokex_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