How to fix fatal: Not a valid object name: 'main' in Git

GitBEGINNERLOWUpdated Dec 6, 2025· 241 views

The 'fatal: Not a valid object name' error occurs when Git cannot find the branch, tag, or commit you're referencing. This typically happens in freshly initialized repositories before the first commit, or when referencing a branch that doesn't exist yet.

Quick fix

Fixes fatal: Not a valid object name: 'main'

# Check commit history
git log --oneline

# If this shows "fatal: your current branch 'main' does not have any commits yet"
# or "fatal: bad default revision 'HEAD'", you need to make your first commit
  1. Check if you have any commits
  2. Make your first commit
  3. Configure Git user identity (if commits fail)
  4. Fetch remote branches first
git — error
# Check commit history
git log --oneline
# If this shows "fatal: your current branch 'main' does not have any commits yet"
# or "fatal: bad default revision 'HEAD'", you need to make your first commit
fatal: Not a valid object name: 'main'

What this error means

When you see the error "fatal: Not a valid object name: 'main'" (or 'master', or any other branch name), Git is telling you that the branch or reference you specified doesn't exist in the repository. In Git, everything is stored as objects - commits, trees, blobs, and tags. When you reference a branch name like "main", Git looks for the corresponding commit object that the branch points to. If no such object exists, you get this error. The most common scenario is trying to create a new branch or switch branches in a repository that has just been initialized with `git init` but has no commits yet. Before your first commit, there are no objects in the repository, and therefore no valid branch can exist. Git shows "main" or "master" as your branch in `git status`, but technically it doesn't exist until you make your first commit. This error can also occur when you reference a remote branch that hasn't been fetched, use an incorrect branch name, or work with a repository that has an unusual state.

Typical symptoms

  • Error appears when running 'git branch <new-branch-name>' in an empty repository
  • Error occurs when trying to run 'git checkout -b <branch>' before any commits
  • The 'git branch' command shows no output in a new repository
  • Trying to reference 'origin/main' fails before running 'git fetch'
  • Error appears in CI/CD pipelines working with newly initialized repos
  • Creating a worktree fails with 'not a valid object name'

Common causes

  1. Repository was just initialized but has no commits yet (most common)
  2. Trying to create a branch before making the first commit
  3. Referencing a remote branch that hasn't been fetched
  4. Typo in branch name or referencing a non-existent branch
  5. Running 'git init' inside an already existing repository
  6. Git user identity not configured (preventing commits)
  7. Repository is in a corrupted state
  8. Working with a shallow clone that doesn't have the referenced commit

How to fix "fatal: Not a valid object name: 'main'"

1Check if you have any commits

First, verify whether your repository has any commits:

bash
# Check commit history
git log --oneline

# If this shows "fatal: your current branch 'main' does not have any commits yet"
# or "fatal: bad default revision 'HEAD'", you need to make your first commit

You can also check with:

bash
# List all branches - empty output means no commits exist
git branch -a
2Make your first commit

If you have no commits yet, create one:

bash
# Create a file if the directory is empty
echo "# My Project" > README.md

# Stage the file
git add README.md

# Create the initial commit
git commit -m "Initial commit"

After this commit, your default branch (main/master) will exist and you can create other branches:

bash
# Now this will work
git branch feature-branch
3Configure Git user identity (if commits fail)

If your commit fails with an identity error, configure your user info:

bash
# Set your name and email
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

# Then try the commit again
git commit -m "Initial commit"
4Fetch remote branches first

If you're trying to reference a remote branch like origin/main:

bash
# Fetch all remote branches
git fetch origin

# Now you can reference remote branches
git checkout -b local-branch origin/main

# Or see all available remote branches
git branch -r
5Use checkout -b with a start point (alternative)

Instead of creating a branch with git branch, use git checkout -b which creates and switches in one step. In a fresh repo, this can work without specifying a base:

bash
# Create and switch to a new branch
git checkout -b main

# Or with the newer 'switch' command
git switch -c main

This changes HEAD to point to the new branch name, even without commits. Your first commit will then be on this branch.

6Verify the branch name is correct

If you're referencing an existing branch, make sure the name is spelled correctly:

bash
# List all local branches
git branch

# List all remote branches
git branch -r

# List all branches (local and remote)
git branch -a

Branch names are case-sensitive. "Main", "main", and "MAIN" are three different branches.

7Check for nested repository issues

If you accidentally ran git init inside an existing repository, it can cause issues:

bash
# Check if you're in a nested repo
git rev-parse --show-toplevel

# If the path seems wrong, navigate to the correct root
# and remove the nested .git folder if needed

Be very careful when removing .git directories to avoid losing work.

Advanced notes

### Understanding Git's Object Model

Git stores everything as objects in the .git/objects directory. When you initialize a repository with git init, this directory is created but empty (except for the pack and info subdirectories). The HEAD file points to refs/heads/main (or master), but that ref file doesn't exist yet because there are no commits.

You can verify this:

bash
# In a fresh repo, this shows the intended branch but ref doesn't exist
cat .git/HEAD
# refs/heads/main

# This file won't exist until first commit
ls .git/refs/heads/
# (empty)

### Changing the Default Branch Name

If you prefer a different default branch name, you can configure it globally:

bash
# Set default branch for new repositories
git config --global init.defaultBranch main

Or change the branch name in an existing repo before first commit:

bash
# Rename the current branch (even before first commit)
git branch -m main
# Or
git branch -m master main

### CI/CD Pipeline Considerations

In CI/CD environments, you may encounter this error when:

1. Shallow clones: Using --depth 1 may not fetch all refs. Use git fetch --unshallow if needed.

2. Nx/Monorepo tools: Tools like Nx that use git diff against a base branch need that branch to exist. Fetch it explicitly:

bash
git fetch origin main:main

3. GitHub Actions: Some actions may need explicit branch fetching:

yaml
- uses: actions/checkout@v4
     with:
       fetch-depth: 0  # Fetch all history

### Orphan Branches

If you intentionally want to create a branch with no history (orphan branch), use:

bash
git checkout --orphan new-branch
# or
git switch --orphan new-branch

This creates a new branch with no commits, and your next commit will be the root commit of that branch's history.

Frequently asked questions

What does "fatal: Not a valid object name: 'main'" mean?
When you see the error "fatal: Not a valid object name: 'main'" (or 'master', or any other branch name), Git is telling you that the branch or reference you specified doesn't exist in the repository. In Git, everything is stored as objects - commits, trees, blobs, and tags. When you reference a branch name like "main", Git looks for the corresponding commit object that the branch points to.
How do I fix "fatal: Not a valid object name: 'main'"?
The 'fatal: Not a valid object name' error occurs when Git cannot find the branch, tag, or commit you're referencing. This typically happens in freshly initialized repositories before the first commit, or when referencing a branch that doesn't exist yet.
What causes "fatal: Not a valid object name: 'main'"?
Repository was just initialized but has no commits yet (most common) Trying to create a branch before making the first commit Referencing a remote branch that hasn't been fetched
Is the "fatal: Not a valid object name: 'main'" error serious?
It is a low-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading