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.
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.
First, check what branches and tags are available in your repository:
# 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-refIf your target branch appears in the remote list (e.g., remotes/origin/feature-branch) but not locally, you need to fetch it first.
If the branch exists on the remote but not locally, fetch it:
# Fetch all branches and tags from origin
git fetch origin
# Fetch all remotes
git fetch --all
# Fetch with tags
git fetch --tagsAfter fetching, you can reference the remote tracking branch directly:
# Archive using the remote tracking branch
git archive origin/main -o archive.tar.gzGit branch names are case-sensitive. Verify the exact name:
# 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-branchCommon mistakes include:
- Main vs main vs master
- feature/MyFeature vs feature/myfeature
- Extra spaces in the branch name
If you just ran git init, there's no master/main branch yet because no commits exist:
# 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.gzThe default branch (master or main) only exists after the first commit.
Shallow clones may not have all commits. Unshallow the repository:
# 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=100After unshallowing, the previously missing commits should be available.
Git archive accepts various reference formats:
# 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### 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:
- run: git fetch --all3. 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:
# 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:
git archive --remote=ssh://[email protected]/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.
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