failed to push some refs
This error occurs when you attempt to push local commits to a remote repository that contains commits you do not have locally.
Usually happens because:
- ☑ Remote repository branch contains commits you lack locally
- ☑ Your branch history diverged from the remote tracking head
- ☑ Direct pushing is blocked by remote branch protection rules
🔍 Quick Checklist:
What is failed to push some refs?
This error is triggered when Git rejects a push operation because your local branch is behind its remote counterpart. This typically happens when another team member has pushed updates to the remote repository after your last pull. To prevent you from overwriting their changes, Git blocks your push until you fetch and integrate the new remote commits into your local branch.
Common Causes
- Remote branch contains newer commits: Another developer has pushed commits to the remote branch that you do not have locally.
- Non-fast-forward push attempt: The remote branch history has diverged from your local history, making a fast-forward merge impossible.
- Branch protection rules: The remote hosting service blocks direct pushes to the branch (e.g. protected 'main' branch requiring Pull Request approvals).
| Cause | Frequency |
|---|---|
| Newer commits exist on remote branch | ⭐⭐⭐⭐⭐ |
| Remote branch is protected (rules constraint) | ⭐⭐⭐⭐ |
| Diverged local history via git commit --amend | ⭐⭐⭐ |
Common Mistakes
- Using raw `git push --force` without verifying if teammates have pushed new commits, which permanently destroys their work on the remote server.
- Forgetting to check which branch you are currently on before running pull/push operations.
How to Fix
Git Operations & Verification
Fetch and merge the latest remote history into your local tracking branch, then push again.
# 1. Pull changes to reconcile branch history
$ git pull origin main
# 2. Stage and commit any merge conflicts if they occur, then push
$ git push origin mainPlatform Specific Fixes
Verify tracking branch names matching the remote repository.
# Check local branch and tracking status
git branch -vvBest Practices
- Run `git fetch` regularly to inspect remote updates before writing code on the same lines.
- Utilize short-lived, feature-specific branches instead of committing directly to the shared `main` or `developer` branches.
Frequently Asked Questions (FAQ)
Q: What does 'failed to push some refs' mean?
It means the remote branch has commits that you do not have locally, so Git blocks the push to prevent overwriting other developers' changes.
Q: How do I fix it?
Run 'git pull origin <branch-name>' to pull the remote commits, resolve any conflicts if they occur, and then run 'git push' again.
Q: What is the difference between '--force' and '--force-with-lease'?
'--force' will overwrite the remote branch regardless of its state. '--force-with-lease' checks if someone else has pushed new commits since your last fetch; if so, it aborts, protecting their work from being overwritten.
Q: Why does 'git pull' fail with 'reconcile divergent branches'?
Modern Git requires you to specify a merge or rebase strategy when histories diverge. Run 'git config pull.rebase false' (to merge) or 'git config pull.rebase true' (to rebase) globally.