[Git] Error: failed to push some refs — updates were rejected because the remote contains work you do not have locally — How to Fix It
Summary
The Git error error: failed to push some refs appears when your local branch has diverged from the remote. Git blocks the push to prevent overwriting remote commits you don’t have locally. The fix is to first pull or rebase your branch with the remote repository, resolve any conflicts, and then push again once both histories are synchronized.
Context
When you push a branch to a remote like origin, Git checks whether your local history is an ancestor of the remote branch. If someone has pushed new commits since your last pull, the histories diverge, and Git refuses a non–fast-forward update. This safeguard prevents accidental data loss from overwriting others’ work. The problem is frequent in shared repositories, especially when multiple contributors push to main or develop simultaneously. It can occur on any platform — Windows, macOS, or Linux — and in any Git client or IDE such as VS Code or Git Bash.
Probable Cause
- Other contributors pushed new commits to the same branch before your push.
- Your local branch is behind the remote and missing upstream commits.
- You rebased, amended, or force-modified commits locally, creating a different commit tree.
- Branch protection rules on the remote preventing overwriting of protected history.
Quick Fix
Synchronize your local and remote branches safely with these steps:
- Confirm you are on the correct branch (usually
mainormaster):
git status
- Fetch the latest changes from the remote without merging yet:
git fetch origin
- Compare your local and remote histories:
git log main..origin/main --oneline # Commits on remote not in local
git log origin/main..main --oneline # Commits on local not in remote
- Integrate the remote updates. Choose one of the following:
- Clean rebase (recommended):
git pull --rebase origin main
- Simple merge (safe but creates merge commits):
git pull origin main
- Resolve any merge conflicts, edit files if needed, then stage and commit:
git add .
git commit
- Push your branch again after alignment:
git push origin main
Full Example
A developer tries to push after working locally for several hours:
git push origin main
Git rejects it with:
error: failed to push some refs to 'https://github.com/user/repo.git'
hint: Updates were rejected because the remote contains work that you do not have locally.
They inspect the divergence:
git fetch origin
git log main..origin/main --oneline
After confirming there are upstream commits, they safely rebase and push:
git pull --rebase origin main
# (resolve conflicts if any)
git push origin main
The push now succeeds, and both local and remote histories are aligned.
Pitfalls & Debug
- Symptom: Push still rejected after rebase → Fix: Check if you’re pushing to the correct branch with
git branch -vv. - Symptom: Conflict during rebase → Fix: Resolve manually,
git addthe file, and rungit rebase --continue. - Symptom: Multiple collaborators pushing to main → Fix: Use feature branches and open pull requests instead of direct pushes.
- Symptom: You rewrote history (e.g.,
git commit --amend) → Fix: Push with--force-with-leaseonly if you understand the impact. - Symptom: Remote branch protected → Fix: Check repository rules or request maintainer review.
Validation & Next Steps
After synchronization, verify that your branch is fully up to date:
git fetch --all
git status
It should display “Your branch is up to date with 'origin/main'.” For extra confirmation, visualize the commit graph:
git log --graph --oneline --all
To avoid future rejections, always pull before starting new work and consider enabling branch protection for collaborative safety.
Sources
Git documentation — git-push
Pro Git Book — Working with Remotes
Stack Overflow — “failed to push some refs” troubleshooting threads
Atlassian tutorials — Non–fast-forward updates and safe rebasing