How to fix clean filter 'lfs' failed in Git

GitINTERMEDIATEMEDIUMUpdated Dec 6, 2025· 174 views

The 'clean filter lfs failed' error occurs when Git LFS cannot process a file during staging. This typically indicates Git LFS is not properly installed, has permission issues, or the configuration is corrupted.

Quick fix

Fixes clean filter 'lfs' failed

# Check if git-lfs is installed
git lfs version

# If not found, install it
# macOS
brew install git-lfs

# Ubuntu/Debian
sudo apt-get install git-lfs

# Windows (with Chocolatey)
choco install git-lfs

# Or download from https://git-lfs.github.com
  1. Verify Git LFS is installed
  2. Initialize Git LFS
  3. Check and fix LFS filter configuration
  4. Fix permission issues on .git/lfs directory
git — error
# Check if git-lfs is installed
git lfs version
# If not found, install it
# macOS
brew install git-lfs
# Ubuntu/Debian
sudo apt-get install git-lfs
# Windows (with Chocolatey)
choco install git-lfs
# Or download from https://git-lfs.github.com
clean filter 'lfs' failed

What this error means

The "clean filter 'lfs' failed" error occurs when Git attempts to stage a file that matches your `.gitattributes` LFS patterns, but the Git LFS clean filter process fails to execute properly. When you run `git add` on a file tracked by LFS, Git passes the file content through the "clean" filter defined in your Git configuration. This filter is supposed to replace the actual file content with an LFS pointer (a small text file containing the hash of the actual content). When this filter fails, Git cannot complete the staging operation. This error is particularly common after upgrading Git, reinstalling your operating system, cloning a repository with LFS files when LFS isn't set up, or when there are permission issues with the `.git/lfs` directory. Unlike smudge filter errors (which occur during checkout), clean filter errors happen when you're trying to commit changes.

Typical symptoms

  • Running 'git add' on files tracked by LFS fails with 'clean filter lfs failed'
  • Git commands like 'git status' or 'git diff' fail on LFS-tracked files
  • Error appears after cloning a repository that uses Git LFS
  • Previously working LFS operations fail after system upgrade or Git update
  • Error message includes 'exit status 128' or 'permission denied'

Common causes

  1. Git LFS is not installed or not properly initialized with 'git lfs install'
  2. The git-lfs executable is not in the system PATH or not linked to Git
  3. Permission issues with the .git/lfs directory or temporary files
  4. Corrupted Git LFS configuration in .gitconfig or repository config
  5. Files matching .gitattributes LFS patterns were committed without LFS (need migration)
  6. Very large files exceeding Git LFS server limits or available disk space

How to fix "clean filter 'lfs' failed"

1Verify Git LFS is installed

First, check if Git LFS is installed and accessible:

bash
# Check if git-lfs is installed
git lfs version

# If not found, install it
# macOS
brew install git-lfs

# Ubuntu/Debian
sudo apt-get install git-lfs

# Windows (with Chocolatey)
choco install git-lfs

# Or download from https://git-lfs.github.com

If Git LFS is installed but Git can't find it, you may need to link it:

bash
# Link git-lfs to Git's exec path
ln -s "$(which git-lfs)" "$(git --exec-path)/git-lfs"
2Initialize Git LFS

Even if Git LFS is installed, it needs to be initialized for your user account:

bash
# Initialize LFS for your user account (run once per machine)
git lfs install

# If that doesn't work, force reinstallation
git lfs install --force

This command sets up the global Git hooks and filter configuration needed for LFS to work.

3Check and fix LFS filter configuration

Verify the LFS filters are properly configured in your Git config:

bash
# Check current LFS filter configuration
git config --list | grep lfs

# You should see entries like:
# filter.lfs.clean=git-lfs clean -- %f
# filter.lfs.smudge=git-lfs smudge -- %f
# filter.lfs.process=git-lfs filter-process
# filter.lfs.required=true

If these are missing or incorrect, set them manually:

bash
git config --global filter.lfs.required true
git config --global filter.lfs.clean "git-lfs clean -- %f"
git config --global filter.lfs.smudge "git-lfs smudge -- %f"
git config --global filter.lfs.process "git-lfs filter-process"
4Fix permission issues on .git/lfs directory

Permission problems with the LFS directory can cause clean filter failures:

bash
# Check permissions on the .git/lfs directory
ls -la .git/lfs

# Fix permissions (adjust user/group as needed)
chmod -R 755 .git/lfs
chown -R $(whoami) .git/lfs

# If in CI/CD, ensure the build user has write access

In CI environments like Bitbucket Pipelines or GitHub Actions, you may need to set permissions at the start of your pipeline.

5Check for detailed error logs

Git LFS provides detailed logging to help diagnose issues:

bash
# View the last LFS error details
git lfs logs last

# Enable debug output for more information
GIT_TRACE=1 git add your-file.bin

# Check LFS environment and configuration
git lfs env

The log output often reveals the specific underlying error (permission denied, disk full, network issues, etc.).

6Migrate files that should be LFS pointers

If files matching your .gitattributes were committed before LFS was set up, they need to be migrated:

bash
# Check which files should be LFS pointers but aren't
git lfs ls-files
git lfs status

# Migrate existing files to LFS (creates new commits)
git lfs migrate import --include="*.psd,*.zip,*.bin" --everything

# Or migrate without rewriting history (adds migration commit)
git lfs migrate import --no-rewrite -m "Migrate files to LFS"

After migration, you may need to force push if you rewrote history:

bash
git push --force-with-lease origin main
7Set the correct LFS URL for authentication

If you're using SSH but LFS is trying to use HTTPS (or vice versa), authentication can fail:

bash
# Check current remote URL
git config remote.origin.url

# Set LFS to use the same URL as your remote
git config lfs.url $(git config remote.origin.url)

# Or set it explicitly
git config lfs.url git@github.com:username/repo.git

This is especially important when the SSH-authenticated repository was configured for LFS from a different client.

8Reinstall Git LFS as a last resort

If nothing else works, completely reinstall Git LFS:

bash
# Uninstall LFS hooks from your user account
git lfs uninstall

# macOS - reinstall via Homebrew
brew reinstall git-lfs

# Ubuntu/Debian - reinstall via apt
sudo apt-get install --reinstall git-lfs

# Reinitialize LFS
git lfs install

# Verify installation
git lfs version
git lfs env

After reinstallation, you may need to re-clone repositories that use LFS or run git lfs pull to fetch LFS objects.

Advanced notes

### Understanding Clean vs Smudge Filters

Git LFS uses two filters:
- Clean filter: Runs when you git add a file. Converts file content to an LFS pointer.
- Smudge filter: Runs when you git checkout a file. Converts LFS pointer back to actual file content.

The "clean filter failed" error specifically occurs during the add/staging phase.

### CI/CD Pipeline Considerations

In CI/CD environments, you often need to:

yaml
# GitHub Actions example
- name: Setup Git LFS
  run: |
    git lfs install
    git lfs pull

# Or skip LFS entirely if you don't need the actual files
- name: Checkout without LFS
  uses: actions/checkout@v4
  with:
    lfs: false

### Skipping LFS Temporarily

If you need to bypass LFS temporarily (useful for CI or debugging):

bash
# Skip smudge filter during clone
GIT_LFS_SKIP_SMUDGE=1 git clone <repo-url>

# Configure to skip smudge permanently for a repo
git config --local filter.lfs.smudge "git-lfs smudge --skip -- %f"
git config --local filter.lfs.process "git-lfs filter-process --skip"

# Later, fetch LFS objects on demand
git lfs pull

### File Size Limits

GitHub LFS has a 2GB per-file limit. If you're hitting size limits:
- Check your LFS quota: git lfs env
- Consider using Git LFS with a different storage backend
- Split very large files if possible

### Dealing with Corrupted LFS Objects

If the local LFS cache is corrupted:

bash
# Remove local LFS cache
rm -rf .git/lfs/objects

# Re-fetch LFS objects
git lfs fetch --all
git lfs checkout

Frequently asked questions

What does "clean filter 'lfs' failed" mean?
gitattributes LFS patterns, but the Git LFS clean filter process fails to execute properly. When you run git add on a file tracked by LFS, Git passes the file content through the "clean" filter defined in your Git configuration. This filter is supposed to replace the actual file content with an LFS pointer (a small text file containing the hash of the actual content).
How do I fix "clean filter 'lfs' failed"?
The 'clean filter lfs failed' error occurs when Git LFS cannot process a file during staging. This typically indicates Git LFS is not properly installed, has permission issues, or the configuration is corrupted.
What causes "clean filter 'lfs' failed"?
Git LFS is not installed or not properly initialized with 'git lfs install' The git-lfs executable is not in the system PATH or not linked to Git Permission issues with the .git/lfs directory or temporary files
Is the "clean filter 'lfs' failed" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading