How to fix fatal: invalid filter-spec in Git

GitINTERMEDIATEMEDIUMUpdated Dec 6, 2025· 208 views

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.

Quick fix

Fixes fatal: invalid filter-spec

# 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
  1. Verify filter-spec syntax
  2. Check Git client version
  3. Verify server support for partial clone
  4. Use correct combined filter syntax
git — error
# 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
fatal: invalid filter-spec

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.

Typical symptoms

  • Clone command fails immediately with 'fatal: invalid filter-spec' message
  • Error message includes the malformed filter specification
  • Partial clone works with some filters but not others
  • Error occurs on specific Git hosting providers but not others
  • Clone worked previously but fails after Git version change
  • Server returns 'filter not recognized' or 'filter not supported' warnings

Common causes

  1. Typo in filter-spec syntax (e.g., 'blob:nonse' instead of 'blob:none')
  2. Using unsupported filter type for the Git version or server
  3. Git client version is too old to support partial clone (requires Git 2.17+)
  4. Git server doesn't support partial clone or specific filter types
  5. Missing or incorrect separator in combined filters
  6. Invalid size format in blob:limit filter
  7. Using sparse:oid with a hosting provider that doesn't support it
  8. Tree depth value is missing or not a valid number

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.

Frequently asked questions

What does "fatal: invalid filter-spec" mean?
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.
How do I fix "fatal: invalid filter-spec"?
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 causes "fatal: invalid filter-spec"?
Typo in filter-spec syntax (e.g., 'blob:nonse' instead of 'blob:none') Using unsupported filter type for the Git version or server Git client version is too old to support partial clone (requires Git 2.17+)
Is the "fatal: invalid filter-spec" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading