How to fix error: failed to push some refs to 'origin' in Git

GitBEGINNERMEDIUMUpdated Dec 6, 2025· 264 views

This error occurs when Git cannot push your local commits to the remote repository because your local branch is behind the remote. The fix usually involves pulling remote changes first, then pushing again.

Quick fix

Fixes error: failed to push some refs to 'origin'

git pull origin <branch-name>
  1. Pull remote changes first
  2. Use pull with rebase for cleaner history
  3. Check branch name matches remote
  4. Force push only when necessary
git — error
git pull origin <branch-name>
error: failed to push some refs to 'origin'

What this error means

When you see "failed to push some refs to 'origin'", Git is telling you that the remote branch has commits that your local branch doesn't have. Git refuses to push because doing so would overwrite those commits on the remote. This is a non-fast-forward error. In Git terminology, a "fast-forward" is when your local branch can simply move forward to include all the remote commits. When that's not possible (because both branches have diverged with different commits), Git blocks the push to protect the remote commits. This commonly happens when: - A teammate pushed to the same branch before you - You pushed from a different machine and forgot to pull on your current machine - GitHub's web interface was used to edit files directly - CI/CD pipelines or bots made commits to the branch

Typical symptoms

  • git push fails with 'failed to push some refs' message
  • Error message mentions 'non-fast-forward' updates
  • Push works on some branches but not others
  • Error started occurring after a colleague pushed changes
  • Push worked before but suddenly fails on the same branch

Common causes

  1. Remote branch has commits that don't exist locally (most common)
  2. Another developer pushed to the same branch before you
  3. You used git commit --amend or git rebase on already-pushed commits
  4. Branch name mismatch between local (master) and remote (main)
  5. GitHub web interface was used to edit files or merge PRs
  6. Pre-receive hooks on the remote are rejecting the push
  7. Branch protection rules require pull requests instead of direct pushes
  8. Large files exceeding repository size limits (GitHub: 100MB)

How to fix "error: failed to push some refs to 'origin'"

1Pull remote changes first

The most common fix is to fetch and merge remote changes before pushing:

bash
git pull origin <branch-name>

For example, if you're on the main branch:

bash
git pull origin main

This fetches the remote changes and merges them with your local commits. If there are no conflicts, you can then push:

bash
git push origin main
2Use pull with rebase for cleaner history

If you prefer a linear commit history without merge commits, use rebase instead:

bash
git pull --rebase origin <branch-name>

This replays your local commits on top of the remote commits. After rebasing:

bash
git push origin <branch-name>

When to use rebase:
- Working on a feature branch
- You want a clean, linear history
- Your local commits haven't been shared with others yet

3Check branch name matches remote

Ensure your local branch name matches the remote. GitHub changed the default branch from master to main:

bash
# Check your current branch
git branch

# Check remote branches
git branch -r

# If you need to push to 'main' instead of 'master':
git branch -M main
git push -u origin main

If you're on master locally but the remote only has main:

bash
git checkout master
git branch -M main
git push origin main
4Force push only when necessary

Warning: Force pushing overwrites remote history. Only use this when you understand the consequences.

If you intentionally rewrote history (via rebase or amend) and need to update the remote:

bash
# Safer option - fails if someone else pushed
git push --force-with-lease origin <branch-name>

# Destructive option - use with extreme caution
git push --force origin <branch-name>

Never force push to shared branches like main or develop unless you've coordinated with your team. This can cause others to lose their work.

5Resolve merge conflicts if they occur

If git pull results in conflicts, you'll need to resolve them:

bash
# See which files have conflicts
git status

# Open conflicting files and resolve manually
# Look for markers: <<<<<<<, =======, >>>>>>>

# After resolving, stage the files
git add <resolved-file>

# Complete the merge
git commit

# Now push
git push origin <branch-name>

To abort the merge and return to the previous state:

bash
git merge --abort
6Check for branch protection or hooks

If pull and push still fail, the remote may have restrictions:

GitHub/GitLab branch protection:
- Go to repository Settings > Branches
- Check if the branch requires pull requests
- You may need to create a PR instead of pushing directly

Pre-receive hooks:
- Server-side hooks can reject pushes for various reasons
- Check with your repository administrator

Azure DevOps policies:

bash
# If policies require PRs, create a branch and push there
git checkout -b feature/my-changes
git push -u origin feature/my-changes
# Then create a PR through the web interface

Advanced notes

### Understanding Fast-Forward vs Non-Fast-Forward

A fast-forward push is only possible when your local branch contains all commits from the remote plus your new commits. When both branches have unique commits, Git requires a merge or rebase.

bash
Remote: A -- B -- C
Local:  A -- B -- D

Cannot fast-forward because C and D diverge from B

After git pull:

bash
Local:  A -- B -- C -- D (merge commit)
              \-- D --/

Or after git pull --rebase:

bash
Local:  A -- B -- C -- D' (D replayed on top of C)

### When Force Push is Appropriate

Force push is legitimate when:
- You're working alone on a feature branch
- You ran git commit --amend to fix a commit message
- You rebased to incorporate upstream changes
- You're cleaning up a PR branch before final merge

Always use --force-with-lease instead of --force. It fails safely if someone else pushed to the branch:

bash
git push --force-with-lease origin feature-branch

### Large File Issues

If the error mentions file size limits:

bash
# Check for large files
git rev-list --objects --all | \
  git cat-file --batch-check='%(objecttype) %(objectname) %(objectsize) %(rest)' | \
  awk '/^blob/ {print $3, $4}' | sort -rn | head -20

# Remove large files from history with git-filter-repo
pip install git-filter-repo
git filter-repo --path <large-file> --invert-paths

# Or use Git LFS for legitimate large files
git lfs install
git lfs track "*.psd"
git add .gitattributes

### CI/CD Pipeline Considerations

If this error occurs in CI/CD:
- Ensure the pipeline has the latest code before pushing
- Use git fetch --all followed by proper merge/rebase
- Consider using --force-with-lease for deployment branches
- Set up proper credentials with write access

Frequently asked questions

What does "error: failed to push some refs to 'origin'" mean?
When you see "failed to push some refs to 'origin'", Git is telling you that the remote branch has commits that your local branch doesn't have. Git refuses to push because doing so would overwrite those commits on the remote. This is a non-fast-forward error.
How do I fix "error: failed to push some refs to 'origin'"?
This error occurs when Git cannot push your local commits to the remote repository because your local branch is behind the remote. The fix usually involves pulling remote changes first, then pushing again.
What causes "error: failed to push some refs to 'origin'"?
Remote branch has commits that don't exist locally (most common) Another developer pushed to the same branch before you You used git commit --amend or git rebase on already-pushed commits
Is the "error: failed to push some refs to 'origin'" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading