Git "filtering not recognized by server" - Partial Clone Fails

By Kaveh Alemi·Latchkey

A partial clone with --filter=blob:none asks the server to omit object data and fetch it lazily. If the remote does not advertise the partial-clone capability, the filter is ignored or a later command fails fetching a blob on demand.

What this error means

A git clone --filter=blob:none warns that filtering is not recognized, or a later operation fails trying to lazily fetch a missing object. It happens against servers or mirrors that have partial clone disabled.

git clone output

warning: filtering not recognized by server, ignoring
# or, on lazy fetch:
fatal: missing blob object 'a1b2c3...'
fatal: unable to read tree (a1b2c3...)

Diagnose it: depth, refs, or credentials?

CI checkouts are shallow and detached by default, which breaks anything that needs history or a branch name. Before treating it as a credential problem, confirm what the runner actually fetched.

.github/workflows/ci.yml

- run: |
    git rev-parse --is-shallow-repository
    git rev-parse --abbrev-ref HEAD      # prints HEAD when detached
    git log --oneline -3
    git remote -v
    git for-each-ref --format="%(refname)" | head

Common causes

The server does not support partial clone

Partial clone needs the filter capability on the remote. Older Git servers, some mirrors, and certain hosting tiers do not advertise it, so the --filter request is silently ignored.

Lazy fetch cannot reach the promisor remote

A partial clone defers downloading blobs until needed. If the runner later goes offline from the promisor remote, the on-demand fetch of a missing object fails.

How to fix it

Fall back to a shallow clone

When the server lacks partial-clone support, a shallow clone gives a similar size reduction without needing the filter capability.

Terminal

git clone --depth 1 https://github.com/org/repo.git
# instead of: git clone --filter=blob:none ...

Materialize the objects you need

If you must use partial clone, backfill the blobs you will reference so no lazy fetch happens mid-job.

Terminal

git clone --filter=blob:none https://github.com/org/repo.git
cd repo
git fetch origin --refetch   # or: git rev-list --all | git cat-file --batch-check

The checkout options that fix most of this

.github/workflows/ci.yml

- uses: actions/checkout@v4
  with:
    fetch-depth: 0        # full history: diffs, tags, git describe
    submodules: recursive # submodules are NOT fetched by default
    persist-credentials: false  # if a later step pushes with its own token

How to prevent it

Verify the remote advertises the filter capability before using --filter.
Prefer shallow clones for simple CI size reduction.
Keep the promisor remote reachable for the whole job when using partial clone.

Frequently asked questions

What causes Git "filtering not recognized by server"?

There are 2 common causes: the server does not support partial clone and lazy fetch cannot reach the promisor remote. Partial clone needs the filter capability on the remote.

How do I fix Git "filtering not recognized by server"?

There are 2 fixes depending on which cause you have: fall back to a shallow clone and materialize the objects you need. Work through them in order, since the first is the most common.

What does Git "filtering not recognized by server" actually mean?

A git clone --filter=blob:none warns that filtering is not recognized, or a later operation fails trying to lazily fetch a missing object.

How do I stop Git "filtering not recognized by server" happening again?

Verify the remote advertises the filter capability before using --filter. The prevention section lists 3 changes that keep it from recurring.