Skip to main content
DevOps Insightsguides & answers

Git · troubleshooting

error: src refspec main does not match any

Git has no local branch called main to push: there are no commits yet, the branch is called master, or CI checked out a single commit. Push the branch you have, rename it, or push HEAD:main.

Reproduced on Git 2.50.1, . Where the text says “reproduced”, the behaviour was run on that version, not taken from documentation.

First published

New to this? Read what is actually happening first, then come back to the steps.

On this page · 9 sections

Before you start

  • A terminal in the repository.

Run this first

step 1 of 2
git branch --show-current

Look for main, another name, or empty

Shows the local branch name, or nothing on a detached HEAD.

Work out which cause you have

A few questions to narrow the list. Every answer ends in a command that confirms or rules the cause out — this cannot see your cluster, so nothing here is a certainty until you have checked.

Narrow it down

0 answered · nothing is sent anywhere

What does git branch --show-current print?

Cause space

3 of 3 still possible

  • There are no commits yetCommon
  • Your branch is called master (or something else)Common
  • CI checked out a commit, not a branchOccasional

Nothing ruled out yet. Answer the question above and the branches your answer eliminates will strike through here.

Or diagnose it manually

In this order. The first command usually contains the whole answer.

  1. Step 1

    git branch --show-current

    Shows the local branch name, or nothing on a detached HEAD.

    Look for main, another name, or empty

  2. Step 2

    git log --oneline -1

    Shows whether there is any commit to push.

    Look for A commit, or does not have any commits yet

Every cause, and how to fix it

Ordered by how often each one turns out to be the answer.

There are no commits yet

Common

Right after git init (and maybe git add), nothing has been committed, so the branch does not exist yet.

Confirm

git log --oneline -1

fatal: your current branch 'main' does not have any commits yet

Fix

  • Commit first, then push: git add ., git commit -m "First commit", git push -u origin main.
git add . && git commit -m "First commit" && git push -u origin main

Reproduced on Git 2.50.1.

Your branch is called master (or something else)

Common

The local branch has a different name from the one in the push command, often master versus main, or a typo or different case.

Confirm

git branch --show-current
git branch -a

A name other than main

Fix

  • Push the branch you have: git push -u origin master.
  • Or rename it to match the remote's default and push: git branch -M main then git push -u origin main.
git branch -M main && git push -u origin main

Renames the current branch to main; checked on Git 2.50.1.

CI checked out a commit, not a branch

Occasional

CI checkouts are usually a detached HEAD with no local main, so a step that commits and runs git push origin main fails.

Confirm

git branch --show-current; git status | head -1

An empty branch name and HEAD detached at …

Fix

  • Push the current commit to the branch by name: git push origin HEAD:main (or HEAD:${{ github.ref_name }} in GitHub Actions).
  • Or create the branch first: git switch -c main, then push.
git push origin HEAD:main

Pushes the checked-out commit to the remote's main; works from a detached HEAD.

Understanding it properly

Skip this if you are mid-incident — the working part of the page is above. Worth reading afterwards, because understanding the mechanism is what stops the next one.

In plain terms

git push origin main means: send my local branch main to the remote's main. Git looks for a local branch with that name and finds nothing. That happens before your first commit (a branch only exists once it has a commit), when your branch has another name, or in CI, where the checkout is a single commit with no branch around it.

Words used on this page

Refspec
The source:destination pair a push uses. git push origin main is short for main:main, local main to remote main.
Detached HEAD
A checkout of a commit rather than a branch. CI systems usually check out this way, so no local branch exists.
Unborn branch
A branch name with no commits yet, right after git init. It cannot be pushed until it has a commit.
What is actually happening

Reproduced on Git 2.50.1 with a local test remote: all three situations below printed error: src refspec main does not match any, then error: failed to push some refs, and exited 1.

Before the first commit the branch is unborn: git init names it, but it does not exist as a ref until something is committed. Commit first, then push.

If the repository was created with master as its default branch, there is no main to push. Either push master, or rename it with git branch -M main and push that. Both worked in the reproduction.

In CI, a checkout of a single commit has no local branch at all. git push origin HEAD:main pushes the current commit to the remote's main and worked from a detached HEAD.

A nearby first-push error: git remote add origin URL on a repository that already has an origin prints error: remote origin already exists. Use git remote set-url origin URL to change it instead.

How to tell this is your problem
WhereWhat you see
git pusherror: src refspec main does not match any … error: failed to push some refs to 'URL'
git branch --show-currentmaster instead of main, or nothing (detached HEAD)

How to know it is actually fixed

  • git push prints [new branch] main -> main (or the update), and exits 0.
  • git status shows Your branch is up to date with 'origin/main'.

Stopping it happening again

  • Set the default branch name once: git config --global init.defaultBranch main.
  • In CI scripts, push with an explicit source: git push origin HEAD:BRANCH.

Security considerations

  • Do not reach for git push --force to get past push errors on a shared branch; this error is about naming, not about history.

Sources

Behaviour described here is drawn from official documentation. Where a figure could not be confirmed on an official page it is attributed in the text rather than stated as canonical.

Did this get you to an answer?

No text box on purpose — please do not paste production logs anywhere

Something wrong or out of date? Report it

Where to go next