[Git] Error: src refspec main does not match any — Pushing Before First Commit in Git — How to Fix It

Summary

error: src refspec main does not match any appears when you try to git push before creating your first commit, or when your local branch name doesn’t match the remote’s. Git cannot push a branch that doesn’t yet exist in your repository. The fix is simple: make your initial commit and ensure the branch name matches main (or master, depending on your setup).

Context

This is one of the most common errors after initializing a new repository. It happens because Git pushes only existing branches with commits. If your local repository has no commits, or your branch name differs from the remote branch name, the push command fails — Git can’t find a valid reference (“refspec”) to send.

Probable Cause

  • No commits yet: You ran git push before committing anything.
  • Branch mismatch: Your local branch is master but the remote uses main.
  • Empty remote: The remote repo exists but has no commits to reference.
  • No upstream configured: The local branch isn’t linked to a remote branch.
  • Wrong refspec: You pushed using origin/main even though your local branch has a different name.

Quick Fix

  1. Check your branch name: 
    git branch
  2. If no commits exist, create one: 
    git add . git commit -m "Initial commit"
  3. If branch name mismatch exists:

    Option A — Rename your branch to main:

    git branch -M main

    Option B — Push using the correct name:

    git push origin <your-branch>
  4. Confirm the remote is set correctly: 
    git remote -v
  5. Push again after first commit: 
    git push -u origin main

Example

# Error $ git push origin main error: src refspec main does not match any
Fix

$ git add .
$ git commit -m "Initial commit"
[main (root-commit) a1b2c3d] Initial commit
3 files changed, 45 insertions(+)
$ git push -u origin main
Enumerating objects: 3, done.
Counting objects: 100% (3/3), done.
Writing objects: 100% (3/3), done.

Alternate Scenarios

  • Local branch is 'master', remote expects 'main': 
    git branch -M main git push -u origin main
  • Empty remote initialized via GitHub UI:

    Run your initial push only after committing locally — GitHub won’t accept an empty push.

  • Wrong remote set: 
    git remote set-url origin https://github.com/username/repo.git

Pitfalls & Debug

  • Symptom → “Nothing to commit” but push fails. Fix → You may be on the wrong branch. Run git status and git branch -vv to check.
  • Symptom → You committed, but still get the error. Fix → The branch isn’t tracking any remote. Set it with: 
    git push -u origin main
  • Symptom → Remote repo has only README created online. Fix → Pull it first to merge: 
    git pull origin main --allow-unrelated-histories

Verification & Next Steps

# Confirm commits exist git log --oneline
Check remote

git remote show origin

Confirm branch matches

git branch -vv

Best Practices

  • Always make an initial commit before pushing to remote.
  • Keep branch names consistent across local and remote.
  • When starting a new project, use git clone instead of reinitializing with git init.
  • Use git push -u on first push to set up tracking automatically.

Sources

Git Documentation — git push

GitHub Docs — Using Git

Atlassian — Git Push Explained

Labels

Tool/Git, OS/Cross-platform, Topic/First Push & Branch Setup