Git LFS pointer file checked out instead of content in CI

By Daniel Zoghalchali·Latchkey

The working tree holds the LFS pointer text (a tiny file starting with "version https://git-lfs.github.com/spec/v1") rather than the real binary. The checkout skipped LFS, so nothing downloaded the content.

What this error means

A build reads a supposedly binary file and finds a few lines of text, or tools report an invalid image/archive. Printing the file shows an oid and size, not the real bytes.

git-lfs

version https://git-lfs.github.com/spec/v1
oid sha256:9f8e7d6c5b4a39281706f5e4d3c2b1a0...
size 5242880

Common causes

The checkout did not enable LFS

actions/checkout defaults to lfs: false, so it clones pointers without fetching objects. The smudge filter never replaces them with content.

LFS objects were never pulled

On a manual clone with smudge skipped, or a runner where git lfs is not initialized, the pointers stay as text until git lfs pull runs.

How to fix it

Enable LFS on the checkout

Set lfs: true on the actions/checkout step.
Or after checkout, run git lfs pull to materialize the objects.
Verify the file is now binary, not the pointer text.

.github/workflows/ci.yml

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

Pull objects explicitly after a manual clone

When you clone outside the checkout action, initialize LFS and pull so pointers become content.

Terminal

git lfs install
git lfs pull

Using this in CI

CI checkouts are shallow and detached by default, which changes the answer this command gives you. Commands that read history, branch names, or tags need the checkout configured for it.

.github/workflows/ci.yml

- uses: actions/checkout@v4
  with:
    fetch-depth: 0   # history, tags, and git describe all need this

- run: |
    git rev-parse --is-shallow-repository   # expect false
    git rev-parse --abbrev-ref HEAD          # prints HEAD when detached

How to prevent it

Always set lfs: true when a job needs the tracked binaries.
Run git lfs pull after any manual clone in CI.
Fail early if a known binary starts with "version https://git-lfs".

Frequently asked questions

What causes Git LFS pointer file checked out instead of content in CI?

There are 2 common causes: the checkout did not enable lfs and lfs objects were never pulled. actions/checkout defaults to lfs: false, so it clones pointers without fetching objects.

How do I fix Git LFS pointer file checked out instead of content in CI?

There are 2 fixes depending on which cause you have: enable lfs on the checkout and pull objects explicitly after a manual clone. Work through them in order, since the first is the most common.

What does Git LFS pointer file checked out instead of content in CI actually mean?

A build reads a supposedly binary file and finds a few lines of text, or tools report an invalid image/archive.

How do I stop Git LFS pointer file checked out instead of content in CI happening again?

Always set lfs: true when a job needs the tracked binaries. The prevention section lists 3 changes that keep it from recurring.