Git Failed to Push Some Refs: Fixes That Work

When Git says “failed to push some refs,” it usually means your local branch is behind the remote branch, or you’re trying to push to a branch you don’t have permission to update. The fix is to pull the latest changes (or force push only if you’re certain) and then push again. This article explains the common causes and walks you through the exact commands to resolve the error.

What Does the Error Mean?

Git uses “refs” to point to commits. When you run git push, Git tries to update the remote ref (like refs/heads/main) to point to your local commit. If the remote ref has moved forward since you last fetched, Git refuses to overwrite it—that’s the “non-fast-forward” rejection. The full error message usually includes [rejected] and a hint to use git pull first.

Common Causes

• Remote has new commits you haven’t pulled yet.
• You’re on a protected branch (like main on GitHub/GitLab) where direct pushes are blocked.
• You accidentally pushed to the wrong remote (e.g., a fork instead of the original repo).
• You rewrote history (e.g., with git rebase or git commit --amend) and now your local branch diverges from the remote.

How to Fix It: Step-by-Step

1. Check your status: Run git status to see which branch you’re on and how many commits ahead/behind.
2. Fetch the latest remote state: git fetch origin (or your remote name). This updates your remote-tracking branches without changing your working files.
3. Pull with rebase (recommended): git pull --rebase origin main (replace main with your branch name). This replays your local commits on top of the remote ones, keeping a linear history.
4. Resolve any conflicts if Git asks. Edit the conflicted files, then git add and git rebase --continue.
5. Push again: git push origin main. If it still fails, check if you’re on a protected branch.

If you prefer a merge instead of a rebase, use git pull origin main (without --rebase). That creates a merge commit and is fine for most workflows.

When to Use Force Push (and When Not To)

If you rewrote history (e.g., you amended a commit or squashed), a normal push will be rejected because your local branch no longer shares a common ancestor with the remote. In that case, you can force push with git push --force-with-lease origin main. The --force-with-lease option is safer than --force because it checks that the remote hasn’t changed since you last fetched—if it has, the push is aborted. Only use force push on branches you own or that are explicitly meant for force pushing (like feature branches). Never force push to a shared branch like main without coordinating with your team.

Protected Branches and Permissions

Many remote hosting services (GitHub, GitLab, Bitbucket) allow you to protect branches. If you try to push to a protected branch, you’ll get a rejection even if you’re up to date. The error message might say “protected branch hook declined” or simply “failed to push some refs.” To fix this, either push to a different branch and open a pull request, or ask a maintainer to merge your changes. If you’re the admin, you can temporarily unprotect the branch, but it’s better to follow the pull request workflow.

Other Causes and Quick Checks

• Wrong remote URL: Run git remote -v to see which URL your remote points to. If it’s wrong, update it with git remote set-url origin <new-url>.
• Stale remote-tracking branch: After fetching, check git log origin/main..main to see what you’d be pushing. If you see commits you don’t want, you may have accidentally committed to the wrong branch.
• Large files: If your push fails with a different error (like “file too large”), that’s a separate issue. But sometimes a push can be rejected because the remote has hooks that check for large files.
• Authentication issues: If you get “permission denied” or “could not read Username,” that’s an auth problem, not a ref problem. Check your credentials and remote URL.

Preventing the Problem in the Future

Always pull before you push, especially if you’re working on a shared branch. A good habit is to run git pull --rebase right before you push. This keeps your local branch in sync and avoids the rejection. Also, consider using feature branches for your work—they’re less likely to have conflicts, and if they do, you can resolve them without affecting the main branch.

Frequently Asked Questions

Why does Git say “failed to push some refs” but I haven’t changed anything?

Someone else pushed to the same branch after your last fetch. Even if you didn’t change anything locally, your local branch is behind the remote. Pull first, then push.

What’s the difference between git pull and git fetch?

git fetch only downloads the remote commits and updates your remote-tracking branches. git pull fetches and then merges (or rebases) those changes into your current branch. If you want to see what changed before merging, use fetch first.

Is it safe to force push?

Force push rewrites history on the remote. It’s safe only if you’re the only person working on that branch, or if you’ve coordinated with your team. Use --force-with-lease to avoid overwriting someone else’s changes.

How do I undo a failed push?

A failed push doesn’t change anything—your local commits stay local. You can simply fix the issue (pull, rebase, etc.) and push again. If you already pushed but want to undo that, you’d need to reset and force push, which is more dangerous.

Can I push to a remote branch with a different name?

Yes. Use git push origin local-branch:remote-branch. For example, git push origin my-feature:main would push your local my-feature to the remote main. This is useful when you want to update a branch without switching locally.

What if the remote has commits I don’t want?

If you need to discard remote commits, you can force push your local branch, but that will remove those commits from the remote history. Only do this if you’re sure no one else has based work on them. Otherwise, consider reverting the commits with git revert.

Related

• Turn Off Safari Notifications on Mac: Full Guide
• How Hackers Monetize Stolen Data
• Best PPSSPP Settings for Smooth PSP Emulation