How to fix a git push rejected error: a step-by-step guide

Short answer

A git push rejected error happens when the remote branch contains commits your local copy doesn’t have; Git stops the push to avoid losing history and shows a failed to push some refs message. The usual fix is running git pull first, then pushing again.

This guide walks through why a git push rejected error actually happens, how to read the exact error message, and when to reach for pull, rebase, or force-with-lease instead.

Why a git push rejected error happens

Git expects every branch to have a linear commit history, so when you push, it checks exactly what your local branch is built on top of relative to the remote. If the remote branch has commits you don’t have locally — say a teammate pushed before you, or someone edited a file directly on GitHub — Git classifies your push as “non-fast-forward” and rejects it. The point is to stop your push from silently erasing those commits.

In practice, a git push rejected error almost always comes down to one of three situations:

• More than one person is working on the same branch, and someone pushed before you
• A commit was added to the remote through the GitHub interface (a merged pull request, or a direct file edit) that you don’t have locally
• You rewrote your local history with git rebase, git commit --amend, or git reset, so it no longer lines up with the remote

Read the full error message

The message in your terminal usually looks like this:

! [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.

The important part is the “fetch first” hint — Git is telling you exactly what to do: fetch the remote changes before pushing. If you instead see “Updates were rejected because the tip of your current branch is behind”, the meaning is the same — your branch has fallen behind the remote.

Common git push rejected messages

Message	Typical cause	First fix
! [rejected] main -> main (fetch first)	The remote branch has new commits you don’t have	git pull (or git pull --rebase)
Updates were rejected because the tip of your current branch is behind	Your local branch has fallen behind the remote	Run git fetch to check the state, then git pull
Updates were rejected because the remote contains work that you do not have locally	Someone else pushed before you	Keep history tidy with git pull --rebase
! [rejected] main -> main (non-fast-forward)	Local history was changed via rebase/amend and diverged	Assess the situation, then use --force-with-lease
error: failed to push some refs to '...' (branch mismatch)	Pushing to the wrong remote branch	Check the tracking branch with git branch -vv

How to fix a git push rejected error, step by step

The exact order depends on your scenario, but the following steps resolve a git push rejected error in nearly every case.

1. Run git pull to bring in the remote changes first

The safest and most common fix is running git pull instead of retrying the push directly. This fetches the remote branch into your local copy and, by default, creates a merge commit combining it with your local changes. If there’s no conflict, pushing that merge commit is all you need. If there is a conflict, you’ll hit a standard merge conflict — something we cover in detail in our guide to resolving a git merge conflict.

2. Use git pull --rebase to keep history linear

If you’d rather avoid merge commits branching your history, git pull --rebase fetches the remote changes and replays your commits on top of them, as if you’d written them after the fact. The result is a single linear history — though rebasing can also surface conflicts, resolved one commit at a time. Settling the “merge or rebase” question as a team convention also shapes how often you’ll run into a git push rejected error in the first place.

3. Only reach for force push when you genuinely need to

git push --force overwrites the remote branch with your local history, which means any commits on the remote that you don’t have are permanently lost. Only use it when you’re certain you’re the only one working on that branch, or you’ve deliberately rewritten history (after a rebase, for instance). On a shared branch — especially main or master — a force push can silently wipe out a teammate’s work.

A safer middle ground is git push --force-with-lease. It only allows the force push if nobody has pushed to the remote branch since your last fetch; otherwise it stops and warns you. In almost any situation that calls for a force push, --force-with-lease is the safer choice over a plain --force.

Pushing to the wrong branch can trigger a rejection too

Sometimes a git push rejected error isn’t about diverging history at all — it’s simply pushing to the wrong remote branch name, such as pushing your local main to a remote that was renamed to master. Run git branch -vv to check which remote branch your local branch is tracking; if it doesn’t match, re-establish the tracking relationship with git push -u origin <correct-branch-name>.

Push rejected errors in CI/CD pipelines

A git push rejected error isn’t just something developers see on their own machines — it’s also common in automated deployment (CI/CD) pipelines. When a GitHub Actions workflow tries to commit and push back, say a version tag or a changelog file, the push is rejected if another workflow or a developer updated the same repository in the meantime. The usual fix is adding a git pull --rebase step right before the push, or serializing pushes so concurrent workflows don’t block each other.

Reducing this error when working as a team

A git push rejected error isn’t inherently dangerous — the real risk is ignoring the warning and reaching for --force without thinking. Three habits go a long way toward reducing how often this happens and how risky it is:

• Running git fetch before pushing to check the remote branch’s state
• Running git pull --rebase regularly on long-lived branches
• Banning force pushes on shared branches entirely, allowing them only on personal feature branches

Common mistakes

• Reaching for --force without reading the message. It “solves” the immediate problem but can silently erase real work on the remote; always read the message and understand the cause first.
• Picking pull or pull --rebase without knowing the difference. Both resolve a push rejected error, but the resulting history differs; a choice that doesn’t match the team’s convention can confuse the next push.
• Trying a force push on a shared branch. On branches like main, a force push can wipe out someone else’s commits in a way that’s hard to undo.
• Never checking the tracking relationship (upstream). Pushing to the wrong branch can trigger a rejection even without any real history conflict.

Checklist

• Did you read the full error message — is it “fetch first” or “non-fast-forward”?
• Did you check the remote branch’s current state with git fetch?
• Has your team agreed on merge vs. rebase as the default?
• If a force push is needed, have you considered --force-with-lease?
• Have you confirmed your local branch tracks the correct remote branch with git branch -vv?

Next step

A git push rejected error is a normal part of version control that usually resolves in a few minutes without any data loss — the real thing to watch for is ignoring the warning and reaching for a force push without thinking it through. If you’d like to put your team’s git workflow on a sturdier footing, or set up version control and deployment from scratch for a custom software project, our group company Web Tasarım Ofisi supports technical infrastructure setup for web and software projects.

To plan a custom software project that covers your version control and deployment process, take a look at our custom software service or get in touch with us. We cover another common git teamwork issue in our guide to resolving a git merge conflict.

Sources

• GitHub Docs — Dealing with non-fast-forward errors — the official explanation of non-fast-forward push errors and recommended fixes