error: src refspec main does not match any

Fix "src refspec main does not match any": make a first commit, or rename master with git branch -M main, then git push -u origin main. Covers typos and CI.

easy fix·5 min read·3 causes

By Vishvesh Patel·DevOps Engineer·Updated 21 September 2026

Run these in order. Each one tells you what its output means before you change anything.

• Check whether the branch exists and has a commit

Empty output from git branch means no branch exists yet, because a branch is a pointer to a commit and there are no commits. A "does not have any commits yet" message from git log confirms it.

• If nothing is committed, commit first

Staging alone is not enough. A branch comes into existence with its first commit, which is why git push fails on a repository where files have only been added.

• If the branch exists under a different name, rename it

-M renames the current branch and overwrites an existing name if needed. This is the fix when git init created master and you are pushing main.

If the steps above did not settle it, these are the causes in the order they are usually responsible. Each section explains why it happens and how to confirm it.

src refspec X does not match any means Git looked for a local ref called X to push and found nothing. The remote is irrelevant here; the problem is local.

A branch is a pointer to a commit. With no commits there is no branch, only a HEAD that names one which does not exist yet.

git add is not enough. Staging does not create a commit:

This is by far the most common cause, and it usually happens when following setup instructions and skipping the commit step.

git init created master on older Git, and you are pushing main.

-M is --move --force, which renames the current branch and overwrites the target name if it exists.

Set the default for new repositories so it stops recurring:

Git 2.28 added that setting, and prints a hint about it on git init.

Empty output means detached HEAD: you are on a commit, not a branch, usually after git checkout <sha> or during a rebase.

The refspec is <source>:<destination>, and the source has to exist locally:

HEAD:main is useful in CI, where the checkout is often detached and there is no local branch to name:

A misspelled tag gives exactly the same error, so check with git tag -l.

The old syntax looks like this error waiting to happen:

The second is clearer and does not risk a typo becoming a push.

Most CI systems check out a detached HEAD at a specific commit, so there is no local branch:

Also note that actions/checkout defaults to fetch-depth: 1, a shallow clone, which is fine for pushing a new commit and not for anything needing history.

Why does git push fail on a brand new repository?

Because there are no commits, and therefore no branch to push. A branch in Git is nothing more than a pointer to a commit, so until you make one, main does not exist even though git status shows you on it. Staging files with git add does not create a commit. Run git commit -m "Initial commit" first, then git push -u origin main. This is the single most common cause of this error.

What does the -M flag do in git branch -M main?

It is shorthand for --move --force: rename the current branch to main, overwriting an existing branch of that name if there is one. It is the standard fix when git init created master and your remote expects main. Because it forces, it will overwrite a local main that already exists, so on a repository with several branches check git branch first. Setting git config --global init.defaultBranch main avoids needing it on new repositories.

Why does this happen in CI when it works locally?

Most CI systems check out a detached HEAD at a specific commit rather than a branch, so git branch --show-current returns nothing and there is no local main to push. Use git push origin HEAD:main, which pushes the current commit to the named remote branch without requiring a local branch. In GitHub Actions you can alternatively ask actions/checkout for a branch by passing ref.

What is a refspec?

The <source>:<destination> pair that tells Git what to push where. git push origin main is shorthand for main:main. The source is resolved locally, which is why this error is always about your own repository rather than the remote. Writing the source and destination separately is useful when they differ, as in git push origin HEAD:main, and an empty source as in git push origin :feature/old means delete the remote branch, which is why a typo in that form can be surprising.

How do I delete a remote branch?

git push origin --delete feature/old. The older equivalent, git push origin :feature/old, uses an empty refspec source to mean deletion and still works, but it is easy to mistype into something that pushes instead. The explicit --delete form says what it does. Deleting the remote branch does not remove your local copy, which you delete separately with git branch -d feature/old.

Free, comprehensive DevOps tutorials and learning roadmaps. Master Docker, Kubernetes, CI/CD, and more.

Get notified about new tutorials and features.

• Roadmaps

• Interview Prep

• Certifications

• Company

© 2026 DevOpsLesson. All rights reserved.