What does "failed to push some refs" mean?

This error means the remote branch has commits that your local branch does not have. Git refuses to push because doing so would overwrite those remote commits. You need to integrate the remote changes into your local branch first, then push again.

Should I use git pull --rebase or git pull to fix this?

Both work. "git pull --rebase" replays your local commits on top of the remote changes, creating a linear history with no merge commit. Plain "git pull" creates a merge commit. Rebase is generally preferred for a cleaner history, but either approach resolves the error.

When is it safe to use --force-with-lease?

Use --force-with-lease only when you intentionally rewrote history, such as after running "git commit --amend" or "git rebase -i" on commits you already pushed. Never force push to a shared branch without coordinating with your team. The --force-with-lease flag adds a safety check: it fails if someone else pushed new commits since your last fetch.

What is the difference between --force and --force-with-lease?

"git push --force" overwrites the remote branch unconditionally, even if a teammate pushed new commits. "git push --force-with-lease" only overwrites if the remote branch is exactly where you expect it to be. If someone else pushed in the meantime, --force-with-lease fails and protects their work. Always prefer --force-with-lease over --force.

I get this error even though nobody else pushed. Why?

This can happen if you amended a commit, rebased locally, or if a CI/CD system pushed changes. It also occurs if you pushed from a different machine or branch and forgot. Run "git fetch origin" then "git log --oneline origin/main..HEAD" to see the difference between your local and remote branches.

failed to push some refs How to fix this Git error

Your push was rejected because the remote branch has commits you don't have locally. This is one of the most common Git errors, especially when working in a team. Here is how to fix it safely.

Learn Git step by step Git Glossary

gitquest — enquête

Error explained

What this error means

When you see error: failed to push some refs to 'origin', Git is telling you that the remote branch has moved ahead of your local branch. Someone else pushed commits, or you rewrote history locally, and now the two branches have diverged.

Git refuses to push because doing so would overwrite commits on the remote that your local branch does not contain. This is a safety mechanism to prevent data loss.

The fix is straightforward: pull the remote changes into your local branch first, then push again. In most cases, this takes a single command.

gitquest — error

# You try to push and see this error

$git push origin main

To github.com:user/my-project.git

! [rejected] main -> main (fetch first)

error: failed to push some refs to 'github.com:user/my-project.git'

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

hint: have locally. Integrate the remote changes before pushing again.

Why it happens

Most common

Someone else pushed first

A teammate pushed new commits to the same branch while you were working. Your local branch is now behind the remote. This is the most frequent cause in team environments and is completely normal in collaborative workflows.

After rewrite

You rebased locally

You ran git rebase on commits that were already pushed. Rebase rewrites commit hashes, so Git sees your local branch as diverged from the remote even though the content is similar. This requires a force push to resolve.

After amend

You amended a pushed commit

Running git commit --amend on the last commit changes its hash. If that commit was already pushed, the remote and local histories no longer match. You will need --force-with-lease to update the remote.

How to fix it

Three approaches depending on your situation. Start with pull --rebase, which works in most cases and keeps history clean.

Pull with rebase (recommended)

gitquest — pull rebase

# Fix 1: Pull with rebase, then push (recommended)

$git pull --rebase origin main

remote: Enumerating objects: 5, done.

remote: Counting objects: 100% (5/5), done.

Successfully rebased and updated refs/heads/main.

$git push origin main

To github.com:user/my-project.git

f4e5d6c..a1b2c3d main -> main

Pull with merge

gitquest — pull merge

# Fix 2: Pull with merge, then push

$git pull origin main

remote: Enumerating objects: 5, done.

Merge made by the 'ort' strategy.

README.md | 2 ++

1 file changed, 2 insertions(+)

$git push origin main

To github.com:user/my-project.git

f4e5d6c..b7c8d9e main -> main

Force push (after rewrite only)

gitquest — force push

# Fix 3: Force push (only after intentional rebase/amend)

$git push --force-with-lease origin main

To github.com:user/my-project.git

+ a1b2c3d...f4e5d6c main -> main (forced update)

# --force-with-lease is safer than --force

# It fails if someone else pushed in the meantime

How to prevent it

Pull before you push

Make it a habit to run git pull --rebase before pushing, especially on shared branches. This ensures your local branch includes all remote commits before you try to upload yours.

Use feature branches

Work on a dedicated branch instead of committing directly to main. Feature branches reduce conflicts because fewer people push to the same branch simultaneously. Merge via pull requests when ready.

Fetch often to stay up to date

Run git fetch origin periodically throughout the day. This downloads remote changes without modifying your working directory, so you can see if the remote has moved ahead before you try to push.

Related commands

git push

Upload local commits to a remote repository

git pull

Fetch and integrate remote changes locally

git fetch

Download remote changes without merging them

GitQuest is created by Anaïs (nouvelle fenêtre), web developer and head of education, specializing in tech training and digital accessibility.

Questions about this error

Master Git push and pull without the headaches

GitQuest teaches you collaborative Git workflows through realistic scenarios. No more mysterious push errors.

Start learning Git