How to fix fatal: unable to read tree object in treeless clone in Git

What this error means

The "fatal: unable to read tree object in treeless clone" error indicates that Git needs to access a tree object that wasn't downloaded during the initial partial clone operation, and it cannot fetch it from the remote repository. When you create a treeless clone using `git clone --filter=tree:0`, Git downloads only commit objects initially. Tree objects (which represent directory structures) and blob objects (file contents) are fetched on demand when needed. This makes the initial clone extremely fast, especially for large repositories. This error typically occurs when: - **Network connectivity issues** - Git cannot reach the remote server to fetch the missing tree object - **Remote repository changes** - The tree object no longer exists on the remote (force push, rebase, or garbage collection) - **Corrupted partial clone state** - The local repository's "promisor" configuration is misconfigured - **Server doesn't support partial clone** - The remote Git server may have disabled the feature or doesn't support fetching individual objects - **Operations requiring full history** - Commands like `git log -- <path>` trigger massive tree downloads in treeless clones Treeless clones are designed for CI/CD build environments where you clone, build, and discard. They are not recommended for regular development work due to these limitations.

Typical symptoms

• Clone completes but checkout fails with 'fatal: unable to read tree object'
• git checkout or git switch fails in a repository cloned with --filter=tree:0
• CI/CD pipeline fails during checkout step after a treeless clone
• git log -- <path> triggers the error or causes extremely slow operation
• git blame or git diff operations fail with tree object errors
• Error message includes 'warning: Clone succeeded, but checkout failed'
• Repository shows incomplete checkout with missing files
• git status shows files as deleted that should exist

Common causes

1. Network connectivity prevents fetching missing tree objects from remote
2. The remote repository was force-pushed and the referenced tree no longer exists
3. Git server does not support partial clone object fetching
4. The repository was garbage collected on the server, removing unreferenced trees
5. Firewall or proxy blocking Git's object fetch requests
6. Using --mirror flag with --filter=tree:0 which is incompatible
7. The remote.origin.promisor configuration is missing or incorrect
8. Repository submodules triggering excessive tree fetches during git fetch
9. Attempting operations that require full tree history in a treeless clone
10. Server-side partial clone support was disabled after the initial clone

How to fix "fatal: unable to read tree object in treeless clone"

# Check the remote URL
git remote -v

# Test connectivity to the remote
git ls-remote origin

# Try to fetch explicitly
git fetch origin

# Check proxy settings
git config --global --get http.proxy
git config --global --get https.proxy

# Test with verbose output
GIT_TRACE=1 GIT_CURL_VERBOSE=1 git fetch origin

# Check current partial clone configuration
git config --get remote.origin.partialclonefilter

# Remove the filter setting
git config --unset remote.origin.partialclonefilter

# Fetch all objects with --refetch
git fetch --refetch

# Remove the promisor marking (indicates objects may be missing)
git config --unset remote.origin.promisor

# Verify the conversion
git fsck

# If the above doesn't work, do a fresh clone
cd ..
mv my-repo my-repo-backup
git clone https://github.com/user/repo.git my-repo
cd my-repo

# Copy any local changes from backup if needed

# Blobless clone - downloads all commits and trees, but not file contents
git clone --filter=blob:none https://github.com/user/repo.git

# This is better because:
# - git log -- <path> works without downloading extra objects
# - Only file contents (blobs) are fetched on demand
# - Much more compatible with normal Git workflows

# Unfortunately, you cannot directly convert between filter types
# You need to re-clone with the blobless filter

cd ..
git clone --filter=blob:none https://github.com/user/repo.git my-repo-new

# Prevent fetch from downloading trees for submodule changes
git config fetch.recurseSubmodules false

# Now fetch won't trigger tree downloads for submodule detection
git fetch origin

# When initially cloning, don't recurse into submodules
git clone --filter=tree:0 --no-recurse-submodules https://github.com/user/repo.git

# Initialize submodules separately if needed
git submodule update --init --depth 1

# GitHub Actions example
- uses: actions/checkout@v4
  with:
    filter: blob:none  # Use blobless, not treeless
    submodules: false  # Handle submodules separately

- uses: actions/checkout@v4
  with:
    # Option 1: Shallow clone (usually sufficient for builds)
    fetch-depth: 1

    # Option 2: Blobless clone (if you need history)
    # filter: blob:none

variables:
  # Use shallow clone instead of treeless
  GIT_DEPTH: 1
  # Or for blobless:
  # GIT_STRATEGY: clone
  # GIT_CLONE_PATH: $CI_BUILDS_DIR/$CI_PROJECT_PATH

script:
  - git clone --filter=blob:none --depth 1 $CI_REPOSITORY_URL .

- checkout:
    # CircleCI doesn't support treeless clones well
    # Use shallow clone instead
    depth: 1

checkout([
    $class: 'GitSCM',
    branches: [[name: '*/main']],
    extensions: [[$class: 'CloneOption', shallow: true, depth: 1]],
    userRemoteConfigs: [[url: 'https://github.com/user/repo.git']]
])

# Run fsck to identify issues
git fsck --full

# Check promisor remote configuration
git config --get remote.origin.promisor
git config --get remote.origin.partialclonefilter

# If promisor is incorrectly set
git config remote.origin.promisor true
git config remote.origin.partialclonefilter tree:0

# Try fetching again
git fetch origin

# Attempt to fetch the specific missing tree (if you know the hash)
git fetch-pack --thin origin <tree-hash>

# Or fetch everything from the remote
git fetch --all --prune

# Backup any local work
git stash
git format-patch origin/main --stdout > my-changes.patch

# Fresh clone
cd ..
rm -rf my-repo
git clone https://github.com/user/repo.git my-repo

# Apply saved changes
cd my-repo
git apply ../my-repo-backup/my-changes.patch

Advanced notes

# Check promisor configuration
git config --get remote.origin.promisor  # Should be "true"
git config --get remote.origin.partialclonefilter  # Shows the filter type

git config fetch.recurseSubmodules false

Frequently asked questions

What does "fatal: unable to read tree object in treeless clone" mean?

The "fatal: unable to read tree object in treeless clone" error indicates that Git needs to access a tree object that wasn't downloaded during the initial partial clone operation, and it cannot fetch it from the remote repository. When you create a treeless clone using git clone --filter=tree:0, Git downloads only commit objects initially. Tree objects (which represent directory structures) and blob objects (file contents) are fetched on demand when needed.

How do I fix "fatal: unable to read tree object in treeless clone"?

This error occurs when Git cannot read a required tree object in a partial clone created with --filter=tree:0. Treeless clones only download commit objects initially, fetching trees on demand. The fix typically involves converting to a full clone, using a blobless clone instead, or ensuring network connectivity to fetch missing objects.

What causes "fatal: unable to read tree object in treeless clone"?

Network connectivity prevents fetching missing tree objects from remote The remote repository was force-pushed and the referenced tree no longer exists Git server does not support partial clone object fetching

Is the "fatal: unable to read tree object in treeless clone" error serious?

It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Related errors

• fatal: unable to access 'https://github.com/': Could not resolve host: github.com

  How to fix 'fatal: unable to access - Could not resolve host' in Git

  MEDIUM

• The command git fetch --depth=50 origin +refs/pull/123/merge: exited with 128

  How to fix 'git fetch origin +refs/pull/merge exited with 128' in Travis CI

  MEDIUM

• fatal: could not create work tree dir 'repo': Permission denied

  How to fix "could not create work tree dir: Permission denied" in Git

  MEDIUM

• fatal: the request was too large; try breaking it up

  How to fix 'the request was too large; try breaking it up' in Git

  MEDIUM

• API rate limit exceeded

  How to fix 'API rate limit exceeded' in GitHub

  MEDIUM

• fatal: destination path already exists and is not an empty directory

  Destination Path Already Exists and Is Not Empty

  LOW

Official resources & further reading

• 📚Git Official Documentation
• 📖
  Git - Partial Clone Documentation(Official Docs)
• 📝
  Get up to speed with partial clone and shallow clone - GitHub Blog
• 📝
  Git clone: a data-driven study on cloning behaviors - GitHub Blog
• 💬
  How do I convert an existing Git repo to a treeless clone? - Stack Overflow(Stack Overflow)
• 💬
  Equivalent of 'unshallow' for a treeless/blobless clone - Stack Overflow(Stack Overflow)
• 📖
  Git Partial Clone Now Supported in Azure DevOps(Official Docs)