error: failed to push some refs

Git’s error: failed to push some refs error means your push was rejected because the remote branch contains commits that you don’t have in your local branch.

What It Means

Git enforces that remote branches are not overwritten. When you try to git push, Git checks if the remote branch has commits that your local branch doesn’t know about. If it does, Git rejects the push — your local history has diverged from the remote, and pushing would overwrite the remote’s commits.

The full error message includes a hint:

hint: Updates were rejected because the remote contains work that you do not
hint: have locally.

Why It Happens

• Someone else pushed commits to the same branch while you were working.
• You committed to a branch locally, then someone else merged a PR to the remote branch.
• You made changes directly on GitHub/GitLab (e.g., editing a file in the browser) and didn’t pull first.
• You rebased or amended commits that were already pushed, creating a divergent history.

How to Fix It

1. Pull the latest changes with rebase

git pull --rebase origin main

This fetches the remote commits and replays your local commits on top of them, producing a linear history.

2. Resolve any conflicts during rebase

If conflicts occur, Git pauses the rebase. Resolve each conflicted file:

# Edit the conflicted files to resolve conflicts
git add <resolved-file>
git rebase --continue

To abort the rebase and return to the previous state:

git rebase --abort

3. Push again

git push origin main

4. Alternative: merge instead of rebase

If you prefer a merge commit over a linear history:

git pull origin main
git push origin main

This creates a merge commit that combines the two histories.

5. Force push (last resort, use with caution)

If you’re working alone on a branch and understand the consequences:

git push --force origin main

Or a safer force-push with lease (checks that no one else pushed to the branch):

git push --force-with-lease origin main