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

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.

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.