Git LFS "Smudge error" / "error downloading object" in CI

The LFS smudge filter tried to download an object during checkout and failed mid-transfer. Most often it is a transient network/timeout error against the LFS endpoint, which clears on a retry.

What this error means

A checkout fails with Error downloading object and smudge filter lfs failed, sometimes external filter 'git-lfs filter-process' failed. It is often intermittent - re-running the job succeeds without any change.

git lfs output

Downloading assets/video.mp4 (210 MB)
Error downloading object: assets/video.mp4 (a1b2c3): Smudge error: Error
downloading assets/video.mp4: batch request: io: read/write on closed pipe
error: external filter 'git-lfs filter-process' failed
fatal: assets/video.mp4: smudge filter lfs failed

Common causes

Transient LFS download failure

A dropped connection or timeout while streaming a large object from the LFS store aborts the smudge filter. Nothing is wrong with the repo - a retry usually completes the download.

A large object over a slow or flaky link

Big LFS files over a congested runner network can exceed transfer limits, closing the pipe mid-download and failing the filter.

A genuinely missing object

If the object was never pushed to the LFS store (e.g. pushed with LFS disabled), the download 404s and the smudge fails every time - not a transient case.

How to fix it

Retry the LFS pull

For transient failures, defer LFS and retry the pull with a bounded loop after the plain checkout.

Terminal

GIT_LFS_SKIP_SMUDGE=1 git clone https://github.com/org/repo.git
cd repo
for i in 1 2 3; do git lfs pull && break; sleep 5; done

Raise LFS transfer resilience

Increase concurrency/timeout tolerance and let LFS resume partial transfers.