How to fix Encountered 1 file(s) that should have been pointers, but weren't in Git

GitINTERMEDIATEMEDIUMUpdated Dec 6, 2025· 351 views

This Git LFS error occurs when files that should be tracked by LFS (per .gitattributes) were committed directly to the repository instead of as LFS pointer files. The fix involves re-adding files to LFS or using git lfs migrate.

Quick fix

Fixes Encountered 1 file(s) that should have been pointers, but weren't

git lfs status
  1. Diagnose the problem
  2. Fix with git lfs migrate (recommended)
  3. Alternative: Re-add files manually
  4. Fix all files in repository at once
git — error
git lfs status
Encountered 1 file(s) that should have been pointers, but weren't

What this error means

Git Large File Storage (LFS) works by storing large files on a remote server and keeping only small "pointer files" in your Git repository. These pointer files contain metadata including the file's SHA-256 hash and size, which Git LFS uses to fetch the actual content when needed. When you see this error, it means there's a mismatch between what your `.gitattributes` file says should be tracked by LFS and what's actually stored in the repository. The files matching your LFS patterns contain the full binary content instead of the expected pointer format: ``` version https://git-lfs.github.com/spec/v1 oid sha256:4d7a214614ab2935c943f9e0ff69d22eadbb8f32b1258daaa5e2ca24d17e2393 size 12345 ``` This typically happens when files were committed before LFS tracking was configured, when a colleague committed files without LFS installed, or when files were added through a GUI or IDE that doesn't respect LFS filters. The error is Git LFS's way of protecting you from accidentally pushing large files directly to your repository.

Typical symptoms

  • Error appears during git push, git checkout, or git lfs status
  • Push fails with 'Encountered N file(s) that should have been pointers, but weren't'
  • Repository size unexpectedly large despite LFS being configured
  • git lfs ls-files doesn't show files you expected to be tracked
  • CI/CD pipelines fail at LFS checkout steps

Common causes

  1. Files were committed before adding the file pattern to .gitattributes (most common)
  2. Files were committed by a user or system without Git LFS installed
  3. IDE or Git GUI committed files without running LFS clean filter
  4. Repository was cloned without LFS and files were modified then pushed
  5. Case sensitivity mismatch in .gitattributes patterns (e.g., *.JPG vs *.jpg)
  6. Files were force-added with git add -f bypassing LFS filters

How to fix "Encountered 1 file(s) that should have been pointers, but weren't"

1Diagnose the problem

First, identify which files are causing the issue:

bash
git lfs status

This shows files that LFS is tracking and any that have issues. Also check what patterns are configured:

bash
cat .gitattributes

Verify LFS is installed and configured:

bash
git lfs version
git lfs env
2Fix with git lfs migrate (recommended)

The git lfs migrate import command converts files to LFS pointers. For files only in recent commits without rewriting history:

bash
git lfs migrate import --no-rewrite "path/to/file.ext"

This creates a new commit moving the file to LFS. Verify it worked:

bash
git lfs ls-files | grep "file.ext"

You should see the file listed in the output.

3Alternative: Re-add files manually

If you prefer more control, manually remove and re-add the files:

bash
# Remove the file from Git's index (keeps the working copy)
git rm --cached path/to/file.ext

# Re-add the file (LFS filter will process it)
git add path/to/file.ext

# Commit the change
git commit -m "Convert file to Git LFS"

For multiple files matching a pattern:

bash
git rm --cached "*.psd"
git add "*.psd"
git commit -m "Convert PSD files to Git LFS"
4Fix all files in repository at once

To re-evaluate all files against LFS filters:

bash
# Remove all files from index
git rm -r --cached .

# Re-add all files (LFS filters will be applied)
git add .

# Commit the changes
git commit -m "Fix LFS pointer files"

Warning: This creates a large commit. Review with git status before committing.

5Rewrite history for complete cleanup (optional)

If you need to remove the original large files from history entirely to reduce repository size:

bash
git lfs migrate import --include="*.psd,*.zip,*.tar.gz" --everything

Warning: This rewrites Git history. All team members will need to re-clone or carefully rebase. Use with caution on shared repositories.

For a specific set of commits:

bash
git lfs migrate import --include="*.psd" --include-ref=HEAD~10..HEAD
6Clean up after fixing

After fixing the pointer files, clean up to reclaim space:

bash
# Expire old references
git reflog expire --expire-unreachable=now --all

# Run garbage collection
git gc --prune=now

# Verify LFS files are correct
git lfs fsck
7Push the fixed files

Push your changes to the remote:

bash
git push origin main

If you rewrote history, you'll need force push (coordinate with your team first):

bash
git push --force-with-lease origin main

The --force-with-lease flag is safer than --force as it prevents overwriting others' work.

8Prevent future issues

Ensure all team members have Git LFS installed:

bash
git lfs install

Add a pre-commit hook to catch untracked files. Create .git/hooks/pre-commit:

bash
#!/bin/sh
git lfs status --porcelain | grep "^?" && {
    echo "Error: Files not tracked by LFS that should be"
    exit 1
}

Make it executable:

bash
chmod +x .git/hooks/pre-commit

Advanced notes

### Case Sensitivity on Cross-Platform Teams

Git LFS v3.6.0+ changed how file matching works. If your team uses both macOS/Windows (case-insensitive) and Linux (case-sensitive), use case-insensitive patterns in .gitattributes:

bash
*.[jJ][pP][gG] filter=lfs diff=lfs merge=lfs -text
*.[pP][nN][gG] filter=lfs diff=lfs merge=lfs -text

### LFS in CI/CD Pipelines

CI runners may not have LFS installed or configured. For GitLab CI:

yaml
variables:
  GIT_LFS_SKIP_SMUDGE: "1"  # Skip LFS during clone for speed

before_script:
  - git lfs install
  - git lfs pull

For GitHub Actions:

yaml
- uses: actions/checkout@v4
  with:
    lfs: true

### Checking LFS Pointer Format

A valid LFS pointer file looks like this:

bash
version https://git-lfs.github.com/spec/v1
oid sha256:4d7a214614ab2935c943f9e0ff69d22eadbb8f32b1258daaa5e2ca24d17e2393
size 12345

If you open a file and see this text instead of binary content, LFS checkout hasn't run. Use git lfs checkout to fetch the actual files.

### Multiple LFS Installations

If you have both system-level and Homebrew Git LFS on macOS, you might have version conflicts. Check with:

bash
which git-lfs
git lfs version

Ensure your PATH prioritizes the correct installation.

Frequently asked questions

What does "Encountered 1 file(s) that should have been pointers, but weren't" mean?
Git Large File Storage (LFS) works by storing large files on a remote server and keeping only small "pointer files" in your Git repository. These pointer files contain metadata including the file's SHA-256 hash and size, which Git LFS uses to fetch the actual content when needed. gitattributes file says should be tracked by LFS and what's actually stored in the repository.
How do I fix "Encountered 1 file(s) that should have been pointers, but weren't"?
This Git LFS error occurs when files that should be tracked by LFS (per .gitattributes) were committed directly to the repository instead of as LFS pointer files. The fix involves re-adding files to LFS or using git lfs migrate.
What causes "Encountered 1 file(s) that should have been pointers, but weren't"?
Files were committed before adding the file pattern to .gitattributes (most common) Files were committed by a user or system without Git LFS installed IDE or Git GUI committed files without running LFS clean filter
Is the "Encountered 1 file(s) that should have been pointers, but weren't" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading