Fix: git error: src refspec 'main' does not match any

The Error

You run git push and get:

error: src refspec 'main' does not match any
error: failed to push some refs to 'https://github.com/user/repo.git'

Or variations:

error: src refspec 'master' does not match any

error: src refspec 'my-feature' does not match any

Git cannot find the branch you are trying to push. The branch name does not exist locally, or there are no commits on it.

Why This Happens

When you run git push origin main, Git looks for a local branch named main to push to the remote. If that branch does not exist, Git reports “src refspec does not match any.”

Common causes:

• No commits yet. You initialized a repo but never made a first commit. A branch does not exist until it has at least one commit.
• Wrong branch name. Your local branch is master but you are pushing main, or vice versa.
• Typo in branch name. git push origin mian instead of main.
• Detached HEAD. You are not on any branch.
• Empty repository. The repo was just created with git init and has no history.
• Branch was deleted. The local branch was deleted before pushing.

Fix 1: Make an Initial Commit

The most common cause. A new repo has no commits, so no branch exists yet:

git init
git add .
git commit -m "Initial commit"
git push -u origin main

Without at least one commit, Git has no branch to push. The git init command does not create a main branch — it only sets up the .git directory. The branch is created when you make the first commit.

If you already added files but forgot to commit:

git status
# Shows staged or unstaged files

git add .
git commit -m "Initial commit"
git push -u origin main

Pro Tip: After git init, always make an initial commit immediately, even if it is just a README or .gitignore. This creates the branch and avoids the “src refspec” error entirely.

Fix 2: Check Your Branch Name

Your local branch might have a different name than what you are pushing:

git branch
# Shows all local branches with * next to the current one

If your branch is master but you are pushing main:

# Option 1: Push the correct branch name
git push -u origin master

# Option 2: Rename your branch to main
git branch -m master main
git push -u origin main

If your branch is main but the remote expects master:

git push -u origin main:master
# Pushes local "main" to remote "master"

Check what the remote expects:

git remote show origin
# Shows the remote's default branch (HEAD branch)

Common Mistake: GitHub changed its default branch name from master to main in October 2020. Old tutorials use master, new repos use main. Always check which branch name your remote repository uses.

Fix 3: Fix Detached HEAD State

If you are in detached HEAD state, you are not on any branch:

git status
# HEAD detached at abc1234

Create a branch from the current state:

git checkout -b main
git push -u origin main

Or switch back to an existing branch:

git checkout main
# or
git switch main

For more on detached HEAD, see Fix: Git detached HEAD state.

Fix 4: Fix After git clone of an Empty Repo

When you clone an empty repository:

git clone https://github.com/user/new-repo.git
cd new-repo
# warning: You appear to have cloned an empty repository.

There is no branch yet. Create one:

echo "# My Project" > README.md
git add README.md
git commit -m "Initial commit"
git branch -M main
git push -u origin main

The -M flag forces the branch rename even if the target name already exists.

Fix 5: Fix Branch Name Typos

Check for typos in your push command:

# Wrong
git push origin mian    # typo: "mian"
git push origin mainn   # typo: extra "n"
git push origin Main    # case-sensitive: "Main" ≠ "main"

# Correct
git push origin main

List all local branches to find the right name:

git branch -a
# Local branches:
#   * main
#   feature/login
# Remote branches:
#   remotes/origin/main

Use tab completion to avoid typos. In most shells, typing git push origin m and pressing Tab auto-completes the branch name.

Fix 6: Fix the Default Branch Configuration

Set Git’s default branch name to avoid future mismatches:

# Set default branch name for new repos
git config --global init.defaultBranch main

For an existing repo, rename the branch:

# Rename current branch to main
git branch -m main

# Update the remote
git push -u origin main

# Set the new default on GitHub (via web UI or API):
# Settings → Branches → Default branch → Change to "main"

# Delete the old branch on the remote
git push origin --delete master

Fix 7: Fix Pushing Tags vs Branches

If you are trying to push a tag, not a branch:

# This fails if "v1.0.0" is a tag, not a branch
git push origin v1.0.0
# error: src refspec 'v1.0.0' does not match any

# Push a tag explicitly
git push origin tag v1.0.0
# or
git push origin refs/tags/v1.0.0

Push all tags:

git push origin --tags

Fix 8: Fix Submodule and Worktree Issues

In rare cases, submodules or worktrees can cause this error:

# Check if you are in a submodule
git rev-parse --show-superproject-working-tree

# Check worktree status
git worktree list

If you are accidentally in a submodule directory:

cd ..  # Go back to the main repo
git push origin main

Still Not Working?

Verify the remote URL is correct:

git remote -v
# Should show the correct repository URL

Check if the remote repository exists:

git ls-remote origin
# Lists all refs on the remote
# Empty output means the remote is empty or unreachable

Force push (use with caution):

git push -u origin main --force

Warning: Force pushing overwrites the remote branch. Only use this on new repositories or when you are certain about what you are doing.

Check for credential issues. If the remote URL is correct but push still fails, the error might be an authentication issue disguised as a refspec error. See Fix: error: failed to push some refs for push-related errors and Fix: git permission denied publickey for SSH authentication issues.

For other Git branch issues, see Fix: Git cannot lock ref. For merge-related problems, see Fix: Git refusing to merge unrelated histories.