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

By Kaveh Alemi·Latchkey

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.

What this error means

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

git-lfs

Downloading assets/model.bin (512 MB)
Error downloading object: assets/model.bin (a1b2c3): Smudge error:
error: external filter 'git-lfs filter-process' failed
fatal: assets/model.bin: smudge filter lfs failed

Common causes

The object download was refused or interrupted

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.

A missing object the server cannot serve

If the pointer references an object that was never pushed, the smudge filter has nothing to download and fails.

How to fix it

Skip smudge, then pull explicitly

Clone with smudge disabled so pointers check out without failing.
Run git lfs pull afterward so download errors surface clearly and can retry.
Inspect the printed cause (auth, quota, missing object) and fix that.

Terminal

GIT_LFS_SKIP_SMUDGE=1 git clone https://github.com/acme/app.git
cd app
git lfs pull

Fix the underlying fetch error

A smudge failure is a symptom. Resolve the batch 403/429 or missing object it wraps, then re-run 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

How to prevent it

Ensure objects are actually pushed before CI checks them out.
Keep the LFS token authorized so smudge downloads succeed.
Cache .git/lfs to reduce fetches that can fail mid-checkout.

Frequently asked questions

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?