Git LFS version mismatch on a self-hosted runner in CI

By Kaveh Alemi·Latchkey

A self-hosted runner with an outdated git-lfs can fail transfers or behave differently from hosted runners: missing flags, older batch behavior, or bugs fixed in later releases. Upgrading the binary resolves it.

What this error means

LFS operations that work on GitHub-hosted runners fail only on self-hosted ones, and git lfs version shows a much older release than the hosted image.

git-lfs

$ git lfs version
git-lfs/2.9.2 (GitHub; linux amd64; go 1.13)
# hosted runners ship a far newer git-lfs; behavior differs

Common causes

The runner has an old distro git-lfs package

A stale OS package pins git-lfs to an old release that lacks flags or fixes the workflow relies on.

The binary was never upgraded on the host

Self-hosted runners are not auto-updated, so git-lfs stays at whatever was installed initially.

How to fix it

Upgrade git-lfs on the runner

Install a current git-lfs from the official packagecloud repo or a release tarball.
Run git lfs install to re-register filters.
Verify with git lfs version and re-run the job.

Terminal

curl -s https://packagecloud.io/install/repositories/github/git-lfs/script.deb.sh | sudo bash
sudo apt-get install -y git-lfs
git lfs install

Bake a current git-lfs into the runner image

For container or VM images, install a pinned recent git-lfs during image build so every job starts current.

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

Pin and periodically bump git-lfs in self-hosted images.
Match the git-lfs version to what hosted runners ship.
Check git lfs version in a setup step for drift.

Frequently asked questions

What causes Git LFS version mismatch on a self-hosted runner in CI?

There are 2 common causes: the runner has an old distro git-lfs package and the binary was never upgraded on the host. A stale OS package pins git-lfs to an old release that lacks flags or fixes the workflow relies on.

How do I fix Git LFS version mismatch on a self-hosted runner in CI?

There are 2 fixes depending on which cause you have: upgrade git-lfs on the runner and bake a current git-lfs into the runner image. Work through them in order, since the first is the most common.

What does Git LFS version mismatch on a self-hosted runner in CI actually mean?

LFS operations that work on GitHub-hosted runners fail only on self-hosted ones, and git lfs version shows a much older release than the hosted image.

How do I stop Git LFS version mismatch on a self-hosted runner in CI happening again?

Pin and periodically bump git-lfs in self-hosted images. The prevention section lists 3 changes that keep it from recurring.