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.
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.
First, verify whether your repository has any commits:
# 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 commitYou can also check with:
# List all branches - empty output means no commits exist
git branch -aIf you have no commits yet, create one:
# 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:
# Now this will work
git branch feature-branchIf your commit fails with an identity error, configure your user info:
# Set your name and email
git config --global user.name "Your Name"
git config --global user.email "[email protected]"
# Then try the commit again
git commit -m "Initial commit"If you're trying to reference a remote branch like origin/main:
# 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 -rInstead 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:
# Create and switch to a new branch
git checkout -b main
# Or with the newer 'switch' command
git switch -c mainThis changes HEAD to point to the new branch name, even without commits. Your first commit will then be on this branch.
If you're referencing an existing branch, make sure the name is spelled correctly:
# List all local branches
git branch
# List all remote branches
git branch -r
# List all branches (local and remote)
git branch -aBranch names are case-sensitive. "Main", "main", and "MAIN" are three different branches.
If you accidentally ran git init inside an existing repository, it can cause issues:
# 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 neededBe very careful when removing .git directories to avoid losing work.
### 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:
# 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:
# Set default branch for new repositories
git config --global init.defaultBranch mainOr change the branch name in an existing repo before first commit:
# 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:
git fetch origin main:main3. GitHub Actions: Some actions may need explicit branch fetching:
- 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:
git checkout --orphan new-branch
# or
git switch --orphan new-branchThis creates a new branch with no commits, and your next commit will be the root commit of that branch's history.
warning: BOM detected in file, this may cause issues
UTF-8 Byte Order Mark (BOM) detected in file
fatal: Server does not support --shallow-exclude
Server does not support --shallow-exclude
warning: filtering out blobs larger than limit
Git partial clone filtering large blobs warning
fatal: Server does not support --shallow-since
Server does not support --shallow-since in Git
kex_exchange_identification: Connection closed by remote host
Connection closed by remote host when connecting to Git server