Troubleshooting

error: failed to push some refs: every cause and the fix for each

Git failed to push some refs: read the reason line. Fixes for rejected fetch first, non-fast-forward, src refspec main, hooks and protected branches.

Published ~8 min read
On this page

Short answer: error: failed to push some refs is only Git's summary; the reason is on the line above it. Most often that line reads ! [rejected] main -> main (fetch first) or (non-fast-forward): the remote has commits you do not have, so pull them in with a rebase and push again.

any shell · the common case
git status                        # are you on the branch you think?
git pull --rebase origin main     # put your commits on top of the remote's
git push origin main

Every message below was produced with Git 2.39.5 on Debian 12, pushing from throwaway clones to a local bare repository in a scratch folder, with a second clone pushing in between. The GitHub and GitLab parts are taken from their documentation; we did not push to either.

Read the line above the error

Line before the errorWhat it meansFix
[rejected] ... (fetch first)The remote has commits your clone has never fetchedPull with rebase, push
[rejected] ... (non-fast-forward)You fetched them, but your branch is behind or has divergedPull with rebase, push
src refspec main does not match anyNo local branch with that name, or no commit yetCommit, or use the real branch name
[remote rejected] ... (pre-receive hook declined)A server-side check refused the pushRead the remote: lines
GH006: Protected branch update failedGitHub branch protectionPush a branch, open a pull request
[rejected] ... (stale info)--force-with-lease saw the remote moveFetch and look before forcing
[rejected] v1 -> v1 (already exists)A tag with that name is already on the remoteUse a new tag name
[remote rejected] ... (branch is currently checked out)You pushed into a non-bare repositoryUse a bare repository

If the error comes with Permission denied (publickey) or Authentication failed, Git never got far enough to compare branches; that is a login problem, covered in ssh permission denied (publickey).

Rejected: fetch first and non-fast-forward

Someone (or you, from another machine or the web editor) pushed to the branch after you last pulled. Git refuses to replace their commits with yours. If your clone has not seen those commits yet, the reason is fetch first:

output · git push origin main
To ../remote.git
 ! [rejected]        main -> main (fetch first)
error: failed to push some refs to '../remote.git'
hint: Updates were rejected because the remote contains work that you do
hint: not have locally. This is usually caused by another repository pushing
hint: to the same ref. You may want to first integrate the remote changes
hint: (e.g., 'git pull ...') before pushing again.

After a git fetch the same push reports (non-fast-forward) and the hint says the tip of your current branch is behind its remote counterpart, while git status shows Your branch and 'origin/main' have diverged. The fix is the same for both: integrate, then push.

output · the fix
$ git pull --rebase origin main
Successfully rebased and updated refs/heads/main.
$ git push origin main
To ../remote.git
   01144ed..a634a2f  main -> main
  • git pull --rebase replays your commits on top of the remote's and keeps the history straight. Plain git pull with a merge works too and is the safer choice if your commits were already shared elsewhere.
  • A conflict stops the rebase. Fix the files, git add them, git rebase --continue, then push. git rebase --abort returns to where you started.
  • If the pull says refusing to merge unrelated histories, the two sides share no commit at all, typically a new GitHub repository with a README; see refusing to merge unrelated histories.

error: src refspec main does not match any

Here Git did not even contact the remote for a decision: the branch name you gave does not exist locally. Two causes cover nearly every case.

No commit yet

A fresh git init has no branch until the first commit. Staging files is not enough; in our run, git add followed by git push -u origin main still failed, and so did git push -u origin HEAD (src refspec HEAD does not match any). Commit first:

any shell
git add .
git commit -m "Initial commit"
git push -u origin HEAD     # pushes whatever the current branch is called

master versus main

Git names the first branch after init.defaultBranch, and without that setting Git 2.39 still calls it master. GitHub and GitLab name the default branch of new repositories main. Run git branch --show-current: if it prints master, either push that name or rename the branch with git branch -m main first, as described in how to rename a Git branch. A typo in the branch name gives the same error. Pushing with HEAD instead of a name avoids the whole question. If git branch --show-current prints nothing at all, you are on no branch; detached HEAD explains how to put your commits on one before you push.

[remote rejected] (pre-receive hook declined)

The server ran a check before accepting the push and the check said no. Git itself does not know why; the hook's own explanation is in the lines that start with remote:. We installed a pre-receive hook in our bare repository that refuses every push to see the exact shape:

output · push to a repository with a refusing hook
remote: Direct pushes to main are not allowed, open a merge request
To ../remote.git
 ! [remote rejected] main -> main (pre-receive hook declined)
error: failed to push some refs to '../remote.git'

GitHub's documentation for pre-receive hooks lists typical uses: a required commit message format, a locked branch, and blocking sensitive data by keyword, pattern or file type. No client flag gets past a server hook. Fix what the remote: lines name (amend or rebase the offending commits, remove the blocked file from history) and push again, or push to another branch.

Protected branches on GitHub and GitLab

GitHub's documentation shows the rejection as remote: error: GH006: Protected branch update failed for refs/heads/main. followed by a line with the reason, such as Changes have been requested. Per GitHub, force pushes are blocked on all protected branches by default, and with required reviews changes reach the branch only through a pull request. GitLab protects the default branch by default (no one can force push to it at the default level) and allows force pushes to a protected branch only when the rule's Allowed to force push toggle is on. The fix in both is the same: git switch -c my-change, git push -u origin HEAD, and open a pull or merge request. Creating and pushing branches is covered in how to create a new branch in Git.

When force-with-lease is acceptable

After git commit --amend or a rebase, your branch and the remote have different histories on purpose, and a normal push is rejected as non-fast-forward. Forcing is correct only when all of these hold:

  • it is your own branch, such as a feature branch behind an open pull request;
  • nobody else pushes to it or builds on it, or they know you are rewriting it;
  • it is not main, a release branch or anything protected.

Then use the lease, never plain --force. A lease refuses if the remote branch is not where your last fetch saw it:

output · another clone pushed in the meantime
$ git push --force-with-lease origin main
To ../remote.git
 ! [rejected]        main -> main (stale info)
error: failed to push some refs to '../remote.git'

The catch: any git fetch, including one your editor runs in the background, renews the lease. In our run, after a plain fetch the same command would have overwritten the other clone's commit (--dry-run printed (forced update)). Git 2.30 added --force-if-includes, which also checks that the remote tip you are about to replace is in your branch's reflog, meaning you actually integrated it:

output · lease plus include check after a fetch
$ git push --force-with-lease --force-if-includes origin main
To ../remote.git
 ! [rejected]        main -> main (remote ref updated since checkout)
error: failed to push some refs to '../remote.git'

Fix order

  1. 1Read the line before the error

    The bracketed reason, or the remote: lines, decide everything below.

  2. 2Check branch and commits

    git status and git log --oneline -3: right branch, at least one commit, name matches what you push.

  3. 3Integrate the remote

    git pull --rebase, resolve conflicts, push. This fixes fetch first and non-fast-forward.

  4. 4Respect server rules

    Hooks and protected branches need a changed commit or a pull request, not a flag.

  5. 5Force only your own rewritten branch

    --force-with-lease --force-if-includes, after you have looked at what the remote has.

Pushing to your own VPS or dedicated server

Pushing straight into the working copy of a site on your server ends in refusing to update checked out branch: refs/heads/main and (branch is currently checked out). Git refuses because the push would leave the files on disk out of step with the branch. Push to a bare repository on the server (git init --bare) and deploy from it, for example with a git --work-tree=/var/www/site checkout -f main in its post-receive hook (name the branch: a bare git init on Git 2.39 points HEAD at master, and our hook without a name failed with You are on a branch yet to be born), or, for a simple site, set git config receive.denyCurrentBranch updateInstead in the server's repository: per git-config(1) the push then updates the working tree, and in our test it went through. With updateInstead, keep the server copy free of local edits.

Frequently asked

Why does git say failed to push some refs?

It is a summary line; the reason is printed just above it. Usually the remote branch has commits you do not have (fetch first or non-fast-forward), the branch name does not exist locally (src refspec does not match any), or a server rule rejected the push (pre-receive hook declined or a protected branch).

How do I fix rejected main -> main (fetch first)?

Run git pull --rebase origin main to put your commits on top of the remote's, resolve any conflicts with git add and git rebase --continue, then git push origin main. Do not force push, which would delete the other commits from the remote branch.

What does src refspec main does not match any mean?

Your repository has no local branch called main. Either there is no commit yet, since a branch only exists after the first commit, or the branch has another name such as master. Commit first, check the name with git branch --show-current, or push with git push -u origin HEAD.

When is git push --force-with-lease safe to use?

Only on your own branch after an amend or rebase, when nobody else pushes to it and it is not protected. Add --force-if-includes (Git 2.30 and later) so a background fetch cannot silently approve overwriting commits you never looked at.

Related articles

All troubleshooting