The Problem With ‘src refspec does not match any’

1. Overview

Working with Git is an essential part of any developer’s day-to-day work. However, in the beginning, it could be overwhelming, and error messages might not be obvious. One of the most common issues people receive when starting working with Git is the error with refspec:

error: src refspec master does not match any 
error: failed to push some refs to 'https://github.com/profile/repository.git'

In this tutorial, we’ll learn the reasons for this issue and how to resolve and mitigate it.

2. The Description of a Problem

Many of us have seen the refspec error message at least once within the console. This error occurs on pushing to a remote repository. Let’s try to understand what this line exactly means:

error: src refspec master does not match any

Simply put, this error message tells us that we don’t have a branch we want to push, which is the main reason for this error.

3. Going Through the Steps

The refspec error might appear when we cloned an uninitialized repository and tried to push a local repository. This is how Git services explain setting up a local repository. Here are the steps from GitHub:

$ echo "# repository" >> README.md
$ git init
$ git add README.md
$ git commit -m "first commit"
$ git branch -M main
$ git remote add origin https://github.com/profile/repository.git
$ git push -u origin main

We’ll refer to these steps in the paragraphs below.

4. Pushing a Non-existent Branch

Let’s go step by step through the instruction GitHub provides us.

4.1. Initializing a Repository

The first line creates a README.md file:

$ echo "# repository" >> README.md

The following command will initialize a local Git repository:

$ git init

This command may issue the following message:

hint: Using 'master' as the name for the initial branch. This default branch name
hint: is subject to change. To configure the initial branch name to use in all
hint: of your new repositories, which will suppress this warning, call:
hint: 
hint: 	git config --global init.defaultBranch <name>
hint: 
hint: Names commonly chosen instead of 'master' are 'main', 'trunk' and
hint: 'development'. The just-created branch can be renamed via this command:
hint: 
hint: 	git branch -m <name>

In 2020 GitHub changed the default name of the branch created in a new repository from “master” to “main.” The same changes have happened on GitLab. It’s still configurable on GitHub, GitLab, and Git.

4.2. The First Commit

The subsequent two commands create a commit in our local repository:

$ git add README.md 
$ git commit -m "first commit"

4.3. Renaming a Branch

The interesting thing happens in the following line:

$ git branch -M main

This line is responsible for renaming our current local branch to “main.” This happens because of the reason explained in the hint message. This line will rename our default branch to match the default branch name on our remote repository.

The steps provided by GitHub will contain the default name configured on the platform. However, this remaining became one of the most common reasons behind the refspec error. Let’s see what will happen if we have a local repository that uses “master” as a default branch and a remote which uses “main.” We’ll skip the renaming step for this example and go straight to setting up our remote repository:

$ git remote add origin https://github.com/profile/repository.git

4.4. The Problem

We’ll start experiencing problems on this line:

$ git push -u origin main

Let’s review this line and consult the documentation to understand what’s happening. This line pushes the changes from a branch, in this case, “main,” to a remote repository we configured in the previous line.

That means that the local repository should contain the “main” branch. However, the default local branch name is set to “master,” and we didn’t create a new “main“ branch or rename the “master” branch. In this case, Git won’t be able to find the “main“ branch to push, and we’ll get this error message:

error: src refspec main does not match any
error: failed to push some refs to 'origin'

Now this message makes more sense. As mentioned previously, this error tells us we don’t have the “main” branch. There is a couple of ways to resolve this problem. The first one is to rename our current “master“ branch to “main”:

$ git branch -M main

After the rename operation, we can repeat the push command, which will work without problems. At the same time, we can change the name of the branch we want to push from “main“ to “master” or any name we use as a default in our local repository. The following command will create a “master” branch on the remote repository:

$ git push -u origin master

And lastly, if we want to stick to the “master” name in our local repository and the “main” in our remote repository, we can explicitly set the upstream branch with the following command:

$ git push -u origin master:main

The flag -u will also set the upstream connection between the local “master“ branch and the remote “main“ branch. It means that the next time we can use the command without explicitly identifying the upstream branch:

$ git push

5. Pushing an Empty Repository

Another cause for this problem is pushing an empty repository. However, the reason behind it will be the same – trying to push a branch that doesn’t exist. Let’s assume that we’ve created a new repository. The branches are appropriately named. We added a file but didn’t commit it:

$ echo "# another-test-repo" >> README.md
$ git init
$ git add README.md
$ git branch -M main
$ git remote add origin https://github.com/profile/repository.git
$ git push -u origin main

Although we’re on the “main“ branch, technically, it doesn’t exist. For a branch to be created under .git/refs/heads, it should contain at least one commit. Let’s ensure that the folder .git/refs/heads in our repo is empty at this point:

$ ls .git/refs/heads 

This command should show us an empty folder. Thus, as in the previous example, we’re trying to push a branch that doesn’t exist. A single commit will fix the problem. It will create a branch and make it possible to push the changes:

$ git commit -m "first commit"
$ git push -u origin master

6. Conclusion

Creating and initializing a new local repository isn’t a challenging task. However, skipping steps or blindly following instructions may result in errors. These errors sometimes are not explicitly understandable, especially for new Git users.

In this article, we’ve learned how to deal with refspec errors and what is the reason behind them.