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

> Fix Git partial-clone errors in CI - "fatal: --filter ... filtering not recognized by server" or missing blobs when the remote does not support partial clone.

Source: https://latchkey.dev/learn/git/git-partial-clone-filter-not-supported  
Updated: 2026-06-25

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.

## 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
```

> `actions/checkout` fetches depth 1 and leaves you on a detached HEAD. Anything diffing against a base ref, reading the branch name, or running `git describe` needs `fetch-depth: 0` and usually an explicit ref.

## 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
```

## FAQ

### 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.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt