[Git] Error: error: failed to push some refs to 'origin/main' — Branch Diverged or Out of Sync

Summary

error: failed to push some refs to 'origin/main' occurs when your local branch history differs from the remote branch — usually because someone else pushed changes before you, or you rebased/rewrote commits locally. Git rejects the push to prevent overwriting commits unintentionally. The solution is to pull or rebase to synchronize histories, then push again. In rare cases, a --force push is justified, but only when you fully control the remote branch.

Context

This error happens during git push when Git detects that the remote branch (e.g., origin/main) contains commits your local branch doesn’t. The repository histories diverged — Git refuses to push your commits until you reconcile both sides. This is a safeguard against data loss. The fix depends on whether you want to merge, rebase, or overwrite the remote history.

Probable Cause

Your branch is behind the remote: Another developer or device pushed commits after your last pull.
History rewritten: Someone rebased or force-pushed the remote branch.
Local rebase without update: Your local commit tree diverged from origin/main.
Wrong remote or branch: Pushing to a different remote or to a protected branch.
Protected branch rules: GitHub blocks force pushes to main by default.

Quick Fix

Check current branch:
```
git status
```
Fetch latest remote data:
```
git fetch origin
```
Inspect differences:
```
git log origin/main --oneline git log main --oneline
```
Compare both to see which commits exist remotely vs locally.
Update your branch:
Option 1 (merge):
```
git pull origin main
```
Option 2 (rebase — cleaner history):
```
git pull --rebase origin main
```
Resolve conflicts if they occur. Use git status to identify files, fix conflicts manually, and run:
```
git add . git rebase --continue
```
Push again:
```
git push origin main
```
If you must overwrite remote (use with caution):
```
git push --force origin main
```
Only safe for personal or non-shared branches.

Example

# Error example $ git push origin main To https://github.com/user/repo.git ! [rejected] main -> main (fetch first) 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.
Fix

$ git pull --rebase origin main
$ git push origin main

Alternate Fix — Full Reset (for private projects only)

# WARNING: overwrites remote branch git fetch origin git reset --hard origin/main git push --force origin main

Pitfalls & Debug

Symptom → You recently rebased locally, now push fails. Fix → Use --force-with-lease instead of --force for safer overwrite:
```
git push --force-with-lease origin main
```
Symptom → Push rejected by branch protection rules. Fix → Disable protection temporarily or push to a feature branch, then open a pull request.
Symptom → Collaborator force-pushed main. Fix → Rebase or reset your branch onto the new main to realign history.
Symptom → Pushing to wrong remote. Fix → Verify with git remote -v.

Verification & Next Steps

# Confirm synchronization git fetch --all git log main..origin/main
If empty output → branches are aligned

Best Practices

Always pull before you start working to minimize conflicts.
Use git pull --rebase for linear commit history.
Never force-push shared branches (e.g., main).
Create feature branches for work instead of pushing directly to main.
Enable branch protection rules on GitHub for safety.

Sources

git-push Documentation

GitHub Docs — Using Git

Atlassian — Git Pull and Rebase

Tool/Git, OS/Cross-platform, Topic/Push & Sync Conflicts

Search for an Error

Error Atlas