How to fix fatal: invalid filter-spec in Git

GitINTERMEDIATEMEDIUM

This error occurs when Git cannot parse the filter specification provided to `git clone --filter` or `git fetch --filter`. Common causes include typos in the filter syntax, using unsupported filter types, or version mismatches between client and server.

What this error means

When using Git's partial clone feature with the `--filter` option, Git expects a specific filter-spec format to determine which objects to exclude from the initial clone. The "fatal: invalid filter-spec" error indicates that Git cannot parse the provided filter specification. Git partial clone allows you to clone a repository without downloading all objects (blobs, trees, or commits) immediately. Instead, Git fetches only the objects needed for the current checkout and downloads others on-demand. This dramatically reduces clone time and disk space for large repositories. The filter-spec syntax follows a specific format defined in the git-rev-list documentation. Valid filter types include: - `blob:none` - Exclude all blobs (file contents) - `blob:limit=<size>` - Exclude blobs larger than a specified size - `tree:<depth>` - Exclude trees and blobs at certain depths - `sparse:oid=<blob-ish>` - Use sparse-checkout specification - `combine:<filter1>+<filter2>` - Combine multiple filters This error typically means your filter-spec has a syntax error, uses an unsupported filter type, or the Git server doesn't support partial clone.

How to fix "fatal: invalid filter-spec"

1Verify filter-spec syntax

Check that your filter-spec matches one of the valid formats exactly.

Valid filter formats:

bash

# Blobless clone (most common) - excludes all file contents
git clone --filter=blob:none https://github.com/user/repo.git

# Treeless clone - excludes trees and blobs, fetches on-demand
git clone --filter=tree:0 https://github.com/user/repo.git

# Size limit - excludes blobs larger than 1MB
git clone --filter=blob:limit=1m https://github.com/user/repo.git

# Specific tree depth
git clone --filter=tree:1 https://github.com/user/repo.git

Common syntax mistakes:

bash

# WRONG: typo in 'none'
git clone --filter=blob:nonse https://github.com/user/repo.git

# WRONG: missing equals sign
git clone --filter blob:none https://github.com/user/repo.git

# WRONG: space after equals
git clone --filter= blob:none https://github.com/user/repo.git

# WRONG: using 'tree:none' instead of 'tree:0'
git clone --filter=tree:none https://github.com/user/repo.git

Correct the syntax and retry the clone.

2Check Git client version

Partial clone requires Git 2.17 or later, with different features added in subsequent versions.

Check your Git version:

bash

git --version

Feature availability by version:

| Git Version | Features Added |
|------------|----------------|
| 2.17 | Basic partial clone support |
| 2.19 | blob:limit filter |
| 2.20 | tree:<depth> filter, --filter in fetch |
| 2.22 | Improved sparse checkout support |
| 2.24 | Combined filters |
| 2.25 | --filter improvements |

Upgrade Git if needed:

bash

# Ubuntu/Debian
sudo add-apt-repository ppa:git-core/ppa
sudo apt update
sudo apt install git

# macOS with Homebrew
brew upgrade git

# Windows - download from git-scm.com

After upgrading, verify the version and retry:

bash

git --version
git clone --filter=blob:none https://github.com/user/repo.git

3Verify server support for partial clone

Not all Git servers support partial clone, and support varies by hosting provider.

Server support status:

| Provider | Partial Clone Support |
|----------|----------------------|
| GitHub | Full support (blob:none, tree:0, blob:limit) |
| GitLab | Full support (requires Git 2.22+ server) |
| Bitbucket Cloud | Limited/No support |
| Bitbucket Server | Requires 7.13+ with Git 2.18+ |
| Azure DevOps | Supported since 2022 |
| Gitea | Optional, may be disabled |

Test if server supports partial clone:

bash

# Try a simple filter first
git clone --filter=blob:none --depth=1 https://github.com/user/repo.git test-clone

# If you see a warning like:
# "warning: filtering not recognized by server, ignoring"
# The server doesn't support partial clone

For self-hosted Gitea, enable partial clone:

ini

# In app.ini
[git]
DISABLE_PARTIAL_CLONE = false

If the server doesn't support partial clone, use shallow clone as an alternative:

bash

git clone --depth=1 https://your-server.com/repo.git

4Use correct combined filter syntax

When combining multiple filters, use the correct syntax.

Correct combined filter syntax (Git 2.24+):

bash

# Using 'combine:' prefix with '+' separator
git clone --filter=combine:blob:none+tree:0 https://github.com/user/repo.git

# Or use multiple --filter flags (Git 2.27+)
git clone --filter=blob:none --filter=tree:0 https://github.com/user/repo.git

Common mistakes with combined filters:

bash

# WRONG: missing 'combine:' prefix
git clone --filter=blob:none+tree:0 https://github.com/user/repo.git

# WRONG: using comma instead of plus
git clone --filter=combine:blob:none,tree:0 https://github.com/user/repo.git

# WRONG: spaces around separator
git clone --filter=combine:blob:none + tree:0 https://github.com/user/repo.git

URL-encode special characters if needed:

bash

# If passing through a URL or script
git clone "--filter=combine:blob:none+tree:0" https://github.com/user/repo.git

5Fix blob:limit size format

The blob:limit filter requires a valid size specification.

Valid size formats:

bash

# Bytes (no suffix)
git clone --filter=blob:limit=1048576 https://github.com/user/repo.git

# Kilobytes
git clone --filter=blob:limit=1k https://github.com/user/repo.git
git clone --filter=blob:limit=1024k https://github.com/user/repo.git

# Megabytes
git clone --filter=blob:limit=1m https://github.com/user/repo.git
git clone --filter=blob:limit=10m https://github.com/user/repo.git

# Gigabytes
git clone --filter=blob:limit=1g https://github.com/user/repo.git

Invalid formats that cause errors:

bash

# WRONG: using MB/KB suffixes
git clone --filter=blob:limit=1MB https://github.com/user/repo.git

# WRONG: using spaces
git clone --filter=blob:limit=1 m https://github.com/user/repo.git

# WRONG: decimal values
git clone --filter=blob:limit=1.5m https://github.com/user/repo.git

# WRONG: missing value
git clone --filter=blob:limit= https://github.com/user/repo.git

Note: Size suffixes are case-insensitive (k, K, m, M, g, G all work).

6Handle sparse:oid filter issues

The sparse:oid filter is less commonly supported and has specific requirements.

sparse:oid syntax:

bash

# Reference a sparse-checkout file in the repo
git clone --filter=sparse:oid=HEAD:.sparse-checkout https://github.com/user/repo.git

# Or use a specific blob SHA
git clone --filter=sparse:oid=abc123def456 https://github.com/user/repo.git

Known limitations:

1. GitHub does not support sparse:oid:

bash

fatal: remote error: filter 'sparse:oid' not supported

2. Use sparse-checkout after cloning instead:

bash

# Clone with blobless filter
git clone --filter=blob:none --no-checkout https://github.com/user/repo.git
cd repo

# Configure sparse-checkout
git sparse-checkout init --cone
git sparse-checkout set src/specific-folder

# Checkout
git checkout main

This approach works on all providers that support partial clone.

7Verify and test the fix

After correcting the filter-spec, test your clone command.

Step-by-step verification:

bash

# 1. Test with a simple blobless clone
git clone --filter=blob:none https://github.com/user/repo.git test-repo

# 2. Verify the clone is partial
cd test-repo
git rev-parse --is-partial-clone
# Should output: true

# 3. Check that lazy fetching works
git log --oneline  # Fetches commits
git show HEAD:README.md  # Fetches blob on-demand

Debug with verbose output:

bash

GIT_TRACE=1 git clone --filter=blob:none https://github.com/user/repo.git

If issues persist, try alternative approaches:

bash

# Shallow clone (widely supported)
git clone --depth=1 https://github.com/user/repo.git

# Shallow with single branch
git clone --depth=1 --single-branch --branch main https://github.com/user/repo.git

# Convert shallow to full later if needed
git fetch --unshallow

Advanced notes

### Understanding Partial Clone vs Shallow Clone

These are different mechanisms that can be combined:

| Feature | Partial Clone | Shallow Clone |
|---------|--------------|---------------|
| Flag | --filter=... | --depth=N |
| Excludes | Blobs/trees by criteria | Commits beyond depth |
| On-demand fetch | Yes | No |
| Full history | Yes (metadata) | No |
| Disk savings | Yes (no large files) | Yes (limited history) |

Combined usage:

bash

# Blobless + shallow = fastest clone
git clone --filter=blob:none --depth=1 https://github.com/user/repo.git

# Later, unshallow but keep partial
git fetch --unshallow

### Performance Considerations

Partial clone shifts work from clone-time to checkout-time:

1. Initial clone - Much faster, downloads only metadata
2. First checkout - Downloads blobs for working tree
3. Subsequent operations - May trigger on-demand fetches

Best practices for CI/CD:

bash

# CI pipeline with blobless clone
git clone --filter=blob:none https://github.com/user/repo.git
cd repo

# Pre-fetch blobs needed for build
git sparse-checkout set src/ lib/

### Promisor Remote Configuration

After a partial clone, Git configures the remote as a "promisor":

bash

# View promisor configuration
git config --get remote.origin.promisor
# Output: true

git config --get remote.origin.partialclonefilter
# Output: blob:none

If you need to reconfigure:

bash

# Re-enable partial clone behavior
git config remote.origin.promisor true
git config remote.origin.partialclonefilter blob:none

### Troubleshooting Server-Side Issues

If you manage a Git server:

For Gitea:

ini

[git]
DISABLE_PARTIAL_CLONE = false

For GitLab:
Partial clone is enabled by default. Ensure Git version 2.22+ on the server.

For self-hosted Git (git-daemon):

bash

git config --global uploadpack.allowFilter true
git config --global uploadpack.allowAnySHA1InWant true

### Filter Spec Reference

Complete filter-spec syntax from git-rev-list:

| Filter | Description |
|--------|-------------|
| blob:none | Omit all blobs |
| blob:limit=<n>[kmg] | Omit blobs larger than size |
| tree:<depth> | Omit trees/blobs at depth >= n |
| sparse:oid=<oid> | Use sparse-checkout spec from blob |
| combine:<f1>+<f2> | Apply multiple filters |

Note: The object:type=<type> filter is experimental and not widely supported.

How to fix fatal: invalid filter-spec in Git

What this error means

Typical symptoms

Common causes

How to fix "fatal: invalid filter-spec"

Advanced notes

Related errors

Official resources & further reading