Fix Git LFS errors — smudge filter failed and pointer files

Does this match your situation?

• 'fatal: <file>: smudge filter lfs failed' during clone, pull or checkout.
• An image or binary opens as three lines of text starting 'version https://git-lfs.github.com/spec/v1'.
• 'batch response: This repository is over its data quota.'
• 'Encountered 1 file(s) that should have been pointers, but weren't'
• Everything works for you and breaks for a colleague who does not have LFS installed.

Step-by-step fix

1. Confirm LFS is actually installed and registered

   Installing the git-lfs binary is only half the job. git lfs install writes the clean and smudge filter configuration into your global Git config — without it, Git happily checks out the pointer text and considers the job done.

   step 1Copy

   git lfs version
   git lfs install
   git config --get filter.lfs.smudge
   

   💡git lfs install is per-user, not per-repository. A new machine, a new container or a fresh CI image needs it again.

2. Get past a clone that will not finish

   Skipping the smudge filter tells Git to check out the pointer files and move on, so the clone completes even if the LFS server is unreachable, rate-limited or out of quota. You then fetch the content as a separate, retryable step.

   step 2Copy

   GIT_LFS_SKIP_SMUDGE=1 git clone <url>
   cd <repo>
   git lfs pull
   

   Show the Windows / PowerShell version

   Windows / PowerShellCopy

   $env:GIT_LFS_SKIP_SMUDGE = "1"
   git clone <url>
   cd <repo>
   git lfs pull
   Remove-Item Env:\GIT_LFS_SKIP_SMUDGE
   

3. Replace pointer files with real content

   If your working tree already contains pointer text, git lfs pull downloads the objects and rewrites those files in place. Nothing is lost — the pointer is just an address, and the bytes it points at live on the LFS server.

   step 3Copy

   git lfs pull
   git lfs checkout        # re-expand pointers already in the tree
   git lfs status
   

4. Diagnose which side is failing

   The smudge filter fails for three unrelated reasons: authentication, quota, and corruption. This is how you tell them apart before you start changing things.

   step 4Copy

   GIT_TRACE=1 GIT_CURL_VERBOSE=1 git lfs pull 2>&1 | head -40
   git lfs env
   git lfs fsck
   

   💡A 401 or 403 means credentials; 'over its data quota' means bandwidth or storage on the host; anything else usually means a damaged local cache.

5. Clear a corrupted local LFS cache

   Half-downloaded objects in .git/lfs/objects cause the filter to fail on files that pull perfectly well on another machine. Pruning them forces a clean re-download.

   step 5Copy

   git lfs prune
   rm -rf .git/lfs/objects
   git lfs fetch --all
   git lfs checkout
   

6. Fix binaries that were committed without LFS

   'Files that should have been pointers, but weren't' means real binary content was committed while LFS tracking was in place — usually by someone whose client had no LFS installed. Migrating rewrites those commits to use pointers.

   step 6Copy

   git lfs track "*.psd"
   git add .gitattributes
   
   # convert existing history (rewrites commits - coordinate with your team):
   git lfs migrate import --include="*.psd" --everything
   

   🚨git lfs migrate rewrites history and requires a force-push. Everyone else must re-clone or reset to the new history afterwards.

Why this works

Git LFS is not part of Git. It is a pair of filters Git calls on the way in and out: the clean filter replaces a large file with a small text pointer before it is committed, and the smudge filter swaps that pointer back for the real bytes on checkout. What Git stores and transfers is the pointer — a hundred-odd bytes naming a SHA-256 and a size — while the content travels over a completely separate HTTP API with its own authentication and its own quota. So 'smudge filter lfs failed' never means your repository is damaged. It means Git got the pointers and the second, independent download did not happen, which is why every fix is about that second channel rather than about Git itself.

If that didn’t work

• Check the host's LFS quota page — GitHub bills storage and bandwidth separately, and both stop downloads when exhausted.
• Re-authenticate: git credential reject, then retry, so a stale token is not being replayed.
• Try over SSH rather than HTTPS, or the reverse — LFS negotiates its endpoint from the remote URL.
• On CI, confirm the checkout step enables LFS explicitly (actions/checkout needs lfs: true).

How to stop it happening again

• Set up git lfs track before the first commit of any binary — migrating afterwards means rewriting history.
• Commit .gitattributes in the same commit as the tracking rule, so everyone else picks it up automatically.
• Add git lfs install to your project's setup instructions; it is per-machine and easy to forget.
• Watch the quota on hosted plans — 1 GB of free bandwidth disappears fast on a repository full of textures.

Commands used in this guide

Frequently asked questions