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.
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.
First, check if Git LFS is installed and accessible:
# 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.comIf Git LFS is installed but Git can't find it, you may need to link it:
# Link git-lfs to Git's exec path
ln -s "$(which git-lfs)" "$(git --exec-path)/git-lfs"Even if Git LFS is installed, it needs to be initialized for your user account:
# Initialize LFS for your user account (run once per machine)
git lfs install
# If that doesn't work, force reinstallation
git lfs install --forceThis command sets up the global Git hooks and filter configuration needed for LFS to work.
Verify the LFS filters are properly configured in your Git config:
# 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=trueIf these are missing or incorrect, set them manually:
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"Permission problems with the LFS directory can cause clean filter failures:
# 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 accessIn CI environments like Bitbucket Pipelines or GitHub Actions, you may need to set permissions at the start of your pipeline.
Git LFS provides detailed logging to help diagnose issues:
# 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 envThe log output often reveals the specific underlying error (permission denied, disk full, network issues, etc.).
If files matching your .gitattributes were committed before LFS was set up, they need to be migrated:
# 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:
git push --force-with-lease origin mainIf you're using SSH but LFS is trying to use HTTPS (or vice versa), authentication can fail:
# 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 [email protected]:username/repo.gitThis is especially important when the SSH-authenticated repository was configured for LFS from a different client.
If nothing else works, completely reinstall Git LFS:
# 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 envAfter reinstallation, you may need to re-clone repositories that use LFS or run git lfs pull to fetch LFS objects.
### 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:
# 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):
# 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:
# Remove local LFS cache
rm -rf .git/lfs/objects
# Re-fetch LFS objects
git lfs fetch --all
git lfs checkoutkex_exchange_identification: Connection closed by remote host
Connection closed by remote host when connecting to Git server
fatal: unable to access: Proxy auto-configuration failed
How to fix 'Proxy auto-configuration failed' in Git
fatal: unable to access: Authentication failed (proxy requires basic auth)
How to fix 'Authentication failed (proxy requires basic auth)' in Git
fatal: unable to access: no_proxy configuration not working
How to fix 'no_proxy configuration not working' in Git
fatal: unable to read tree object in treeless clone
How to fix 'unable to read tree object in treeless clone' in Git