How to fix fatal: not a valid object name: branch-name in Git

GitBEGINNERLOWUpdated Dec 6, 2025· 139 views

This error occurs when Git cannot find the branch, tag, or commit you specified in a git archive command. The reference either does not exist locally, has not been fetched from a remote, or contains a typo.

Quick fix

Fixes fatal: not a valid object name: branch-name

# List all local branches
git branch

# List all branches including remote tracking branches
git branch -a

# List all tags
git tag

# Show all refs with their commit hashes
git show-ref
  1. Verify the branch or tag exists locally
  2. Fetch remote branches and tags
  3. Check for typos and case sensitivity
  4. Handle freshly initialized repositories
git — error
# List all local branches
git branch
# List all branches including remote tracking branches
git branch -a
# List all tags
git tag
# Show all refs with their commit hashes
git show-ref
fatal: not a valid object name: branch-name

What this error means

When you run `git archive` with a branch name, tag, or commit hash, Git needs to resolve that reference to an actual object in the repository's object database. The "fatal: not a valid object name" error means Git searched its refs (branches, tags, remote tracking branches) and object database but could not find anything matching what you specified. This commonly happens in several scenarios: you're trying to archive a remote branch that hasn't been fetched yet, the repository is freshly initialized without any commits, the branch name has a typo or incorrect casing, or you're running the command from a shallow clone that doesn't have the full history. Git stores references in the `.git/refs` directory. Local branches live in `refs/heads/`, tags in `refs/tags/`, and remote tracking branches in `refs/remotes/`. When Git says a name is "not valid," it means it couldn't find a matching entry in any of these locations or resolve it to a commit SHA.

Typical symptoms

  • Running git archive fails with 'fatal: not a valid object name: <branch>'
  • Deployment scripts fail during the archive or checkout phase
  • CI/CD pipelines fail when trying to create release archives
  • The error appears immediately after cloning a repository
  • Commands like git show or git log also fail with the same branch name

Common causes

  1. The branch or tag does not exist in the local repository - it may only exist on the remote
  2. The remote tracking branch hasn't been fetched yet with git fetch
  3. The repository was just initialized with git init and has no commits yet
  4. There is a typo or case sensitivity issue in the branch name (Git is case-sensitive)
  5. You're working with a shallow clone that doesn't have the referenced commit
  6. The branch was deleted and the reference no longer exists

How to fix "fatal: not a valid object name: branch-name"

1Verify the branch or tag exists locally

First, check what branches and tags are available in your repository:

bash
# List all local branches
git branch

# List all branches including remote tracking branches
git branch -a

# List all tags
git tag

# Show all refs with their commit hashes
git show-ref

If your target branch appears in the remote list (e.g., remotes/origin/feature-branch) but not locally, you need to fetch it first.

2Fetch remote branches and tags

If the branch exists on the remote but not locally, fetch it:

bash
# Fetch all branches and tags from origin
git fetch origin

# Fetch all remotes
git fetch --all

# Fetch with tags
git fetch --tags

After fetching, you can reference the remote tracking branch directly:

bash
# Archive using the remote tracking branch
git archive origin/main -o archive.tar.gz
3Check for typos and case sensitivity

Git branch names are case-sensitive. Verify the exact name:

bash
# List remote branches with exact names
git branch -r

# Check if a specific ref exists
git show-ref --verify refs/heads/your-branch

# Or use rev-parse to test if a name resolves
git rev-parse --verify your-branch

Common mistakes include:
- Main vs main vs master
- feature/MyFeature vs feature/myfeature
- Extra spaces in the branch name

4Handle freshly initialized repositories

If you just ran git init, there's no master/main branch yet because no commits exist:

bash
# Check if any commits exist
git log --oneline -1

# If this fails, create an initial commit first
git add .
git commit -m "Initial commit"

# Now git archive will work
git archive HEAD -o archive.tar.gz

The default branch (master or main) only exists after the first commit.

5Fix shallow clone issues

Shallow clones may not have all commits. Unshallow the repository:

bash
# Check if you have a shallow clone
git rev-parse --is-shallow-repository

# If true, fetch the full history
git fetch --unshallow

# Or fetch specific depth
git fetch --depth=100

After unshallowing, the previously missing commits should be available.

6Use the correct reference format for git archive

Git archive accepts various reference formats:

bash
# Archive a local branch
git archive main -o main.tar.gz

# Archive a remote tracking branch
git archive origin/main -o main.tar.gz

# Archive a specific tag
git archive v1.0.0 -o release.tar.gz

# Archive a specific commit
git archive abc1234 -o commit.tar.gz

# Archive HEAD (current commit)
git archive HEAD -o current.tar.gz

# Archive from a remote repository directly
git archive --remote=git://example.com/repo.git main -o archive.tar.gz

Advanced notes

### Understanding Git Object Names

In Git, an "object name" can be:
- A branch name (refs/heads/main)
- A tag name (refs/tags/v1.0)
- A remote tracking branch (refs/remotes/origin/main)
- A commit SHA (full or abbreviated)
- A symbolic ref like HEAD

Git resolves these names using a specific order defined in gitrevisions. When resolution fails, you get the "not a valid object name" error.

### CI/CD Pipeline Considerations

In CI/CD environments, repositories are often checked out in specific ways that can cause this error:

1. Shallow clones: Many CI systems use --depth=1 for speed. Use git fetch --unshallow if you need full history.

2. Single branch clones: GitHub Actions and similar tools may only fetch the triggered branch. Add a fetch step:

yaml
- run: git fetch --all

3. Detached HEAD state: CI checkouts often put the repo in detached HEAD state. Use the commit SHA directly or fetch the branch ref.

### Using git show-ref for Debugging

The git show-ref command is invaluable for debugging reference issues:

bash
# List all refs
git show-ref

# Check if a specific ref exists (returns 0 if found)
git show-ref --quiet --verify refs/heads/main && echo "exists"

# Show refs matching a pattern
git show-ref --heads  # local branches only
git show-ref --tags   # tags only

### Remote Archives

If you need to archive from a remote without a full clone:

bash
git archive --remote=ssh://git@github.com/user/repo.git main | tar -xf -

Note: GitHub and some other hosts disable git-upload-archive for security reasons. You may need to clone first.

Frequently asked questions

What does "fatal: not a valid object name: branch-name" mean?
When you run git archive with a branch name, tag, or commit hash, Git needs to resolve that reference to an actual object in the repository's object database. The "fatal: not a valid object name" error means Git searched its refs (branches, tags, remote tracking branches) and object database but could not find anything matching what you specified. This commonly happens in several scenarios: you're trying to archive a remote branch that hasn't been fetched yet, the repository is freshly initialized without any commits, the branch name has a typo or incorrect casing, or you're running the command from a shallow clone that doesn't have the full history.
How do I fix "fatal: not a valid object name: branch-name"?
This error occurs when Git cannot find the branch, tag, or commit you specified in a git archive command. The reference either does not exist locally, has not been fetched from a remote, or contains a typo.
What causes "fatal: not a valid object name: branch-name"?
The branch or tag does not exist in the local repository - it may only exist on the remote The remote tracking branch hasn't been fetched yet with git fetch The repository was just initialized with git init and has no commits yet
Is the "fatal: not a valid object name: branch-name" error serious?
It is a low-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading