# Git LFS "smudge filter lfs failed" during checkout in CI

> Fix "external filter git-lfs smudge failed" / "smudge filter lfs failed" in CI - LFS could not download an object while writing the working-tree file during checkout.

Source: https://latchkey.dev/learn/command-reference/git-lfs-smudge-filter-failed-in-ci  
Updated: 2026-06-30

The LFS smudge filter runs during checkout to replace a pointer with its real content. It failed, usually because the object download was rejected or the network dropped, so git aborts the checkout.

## Using this in CI

CI checkouts are shallow and detached by default, which changes the answer this command gives you. Commands that read history, branch names, or tags need the checkout configured for it.

```.github/workflows/ci.yml
- uses: actions/checkout@v4
  with:
    fetch-depth: 0   # history, tags, and git describe all need this

- run: |
    git rev-parse --is-shallow-repository   # expect false
    git rev-parse --abbrev-ref HEAD          # prints HEAD when detached
```

> `git rev-parse --abbrev-ref HEAD` returns the literal string `HEAD` on a detached checkout rather than a branch name. On GitHub Actions read `github.ref_name` instead; the git command cannot know what it was checked out for.

## FAQ

### What causes Git LFS "smudge filter lfs failed" during checkout in CI?

There are 2 common causes: the object download was refused or interrupted and a missing object the server cannot serve. An auth failure, a quota 429, or a dropped connection during the smudge step means the filter cannot fetch the content and returns non-zero.

### How do I fix Git LFS "smudge filter lfs failed" during checkout in CI?

There are 2 fixes depending on which cause you have: skip smudge, then pull explicitly and fix the underlying fetch error. Work through them in order, since the first is the most common.

### What does Git LFS "smudge filter lfs failed" during checkout in CI actually mean?

A clone or checkout fails with "Error downloading object" followed by "smudge filter lfs failed" and "external filter 'git-lfs filter-process' failed".

### How do I stop Git LFS "smudge filter lfs failed" during checkout in CI happening again?

Ensure objects are actually pushed before CI checks them out. 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