Git cannot find a filter driver defined in .gitattributes, typically because the filter (like Git LFS) is not installed or configured in your Git config.
This error occurs when Git tries to apply a filter driver that is referenced in your .gitattributes file but cannot find the corresponding filter definition in your Git configuration. Filter drivers are used to transform file content during checkout (smudge) and commit (clean) operations. The most common scenario is with Git LFS (Large File Storage), which uses filters to replace large files with pointer files. When .gitattributes specifies `filter=lfs` but Git LFS isn't installed or configured, Git cannot process the files. Git's design separates filter definitions (.gitattributes is versioned and cloned automatically) from filter implementations (configured locally in .gitconfig for security reasons). This means filters must be set up on each machine where the repository is cloned.
Examine the error message to identify the filter name:
# Common filters in error messages:
# - filter=lfs (Git LFS)
# - custom filter names defined in your .gitattributes
cat .gitattributesLook for lines like *.png filter=lfs to see what filters are configured.
If the filter is lfs, install Git LFS:
# Ubuntu/Debian
sudo apt-get install git-lfs
# macOS with Homebrew
brew install git-lfs
# Windows (via Git for Windows, LFS included)
# Or download from https://git-lfs.github.com
# After installation, initialize in your repository
git lfs installThis configures the LFS filters in your Git config.
Check if the filter is properly configured:
# For Git LFS specifically
git lfs env
git config --list | grep filter.lfs
# For any filter
git config filter.<filter-name>.clean
git config filter.<filter-name>.smudgeIf these commands return empty, the filter is not configured.
If you're using a custom filter, add it to your Git config:
# Add globally (affects all repositories)
git config --global filter.myfilter.clean 'command-for-clean'
git config --global filter.myfilter.smudge 'command-for-smudge'
# Or add locally (only this repository)
git config filter.myfilter.clean 'command-for-clean'
git config filter.myfilter.smudge 'command-for-smudge'Ensure the filter commands are in your PATH and executable.
On macOS, if Git LFS is installed via Homebrew but Xcode's Git is used:
# Create symlink so Xcode's Git can find Homebrew's git-lfs
# Note: May fail due to System Integrity Protection (SIP)
sudo ln -s "$(which git-lfs)" "$(git --exec-path)/git-lfs"
# Alternative: Ensure Homebrew Git is first in PATH
export PATH="/opt/homebrew/bin:$PATH"
# Add to ~/.zshrc or ~/.bash_profile to make permanentVerify with which git and which git-lfs.
After configuring the filter, retry your command:
# If you were cloning
git clone <repository-url>
# If you were pulling
git pull
# If you were checking out
git checkout <branch-name>
# For LFS, you can skip smudge during clone if needed
git lfs install --skip-smudge
git clone <repository-url>
cd <repository-name>
git lfs pull # Fetch LFS objects separatelyConverting Existing Files to LFS: If files were committed before LFS was configured and now .gitattributes specifies filter=lfs, you need to migrate them:
git rm --cached -r .
git add -A
git commit -m "Migrate existing files to LFS"Required Filters: You can make a filter mandatory (fail hard instead of silently) by adding required to the filter config:
[filter "myfilter"]
clean = command-clean
smudge = command-smudge
requiredSecurity Note: Git doesn't clone filter configurations automatically for security reasons. This prevents malicious repositories from executing arbitrary code on your system. Always verify what filters a repository uses before setting them up locally.
Filter Command Requirements: Filter commands must read from stdin and write to stdout (streaming). Using file paths with %f is supported but the filter should still stream data, not directly read/write files.
Windows Path Format: On Windows, filter command paths in Git config should use forward slashes with Windows drive letters: C:/path/to/command not C:\path\to\command.
kex_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