How do I find which filter failed?

The message names the filter string from .gitattributes; the filter. .clean and filter. .smudge configuration lines show the exact command Git tried to run.

Git external-filter-failed A clean or smudge filter program exited nonzero and the file operation aborted.

dev@local: ~/project — git

dev@local~/project$git status

error: external filter failed

Diagnostics Translation

A clean or smudge filter program exited nonzero and the file operation aborted.

waiting for resolution...

MediumVersion Control System

Reviewed for reference consistency: August 11, 2026

Code is Safe

SECURE

Git has paused the operation to protect your code. No data has been lost or corrupted.

What To Know

An external content filter, declared by attributes and executed at the file boundary, exited with an error — the operation stopped rather than storing or writing unfiltered content.

Where Did It Fail?

Working Tree

Your local files

add

Staging Index

Prepared changes

commit

Local Repo

Commit history

push/fetch

Remote Server

GitHub/GitLab

Git halted to protect the uncommitted files in your active working directory.

Commands That Trigger This

A repository using Git LFS cloned on a machine without the lfs binary installed

An encoding or formatting filter crashed on unexpected file content

A smudge filter that downloads assets hit a network failure during checkout

Technical Background

Filters are Git's extension point for transforming content at the boundaries — LFS is the canonical user. The failure text includes the filter's declared name, which maps back to the filter.<name> configuration lines and the attribute rule that selected it.

Because the filter runs inside checkout or add, the abort leaves the file unconverted rather than half-converted; the operation can be retried once the filter itself works. The failure is about the tooling around the file, not about repository integrity.

Underlying Causes

The filter binary named in .gitattributes is not installed or not on PATH

The filter process crashed on specific file content

A filter requiring network access failed mid-checkout

Filter configuration points at a nonexistent command through .gitattributes or .git/config

Frequently Asked Questions

The message names the filter string from .gitattributes; the filter.<name>.clean and filter.<name>.smudge configuration lines show the exact command Git tried to run.

The .gitattributes file travels with the repository, so the filter rule activates on checkout even when the tool that implements it was never installed.

Related Git States

no-url-found-for-submodule-pathMedium

A submodule configuration stanza names its path but carries no url key.

pre-commit-hook-failedLow

A local script (hook) executed by Git failed, forcing Git to abort the commit.

bad-config-line-in-fileLow

Git cannot parse its configuration file due to a syntax error.