Buildkite checkout "fatal: reference is not a tree" in CI

By Daniel Zoghalchali·Latchkey

Buildkite checks out the exact commit for the build. "fatal: reference is not a tree" means the working copy or agent git mirror does not contain that commit, often because a branch was force-pushed or the local clone is stale.

What this error means

The checkout phase fails with "fatal: reference is not a tree: <sha>" for the commit Buildkite is trying to build.

$ git checkout -f 4f2a9c1
fatal: reference is not a tree: 4f2a9c1d0e8b7a6f5c4d3e2b1a09f8e7d6c5b4a3

Common causes

A stale agent git mirror

The agent reuses a local mirror that was not fetched after a force-push, so the target commit is absent locally.

The commit was rewritten or removed

A force-push rewrote history and the previously referenced commit no longer exists on the remote branch.

How to fix it

Force a clean checkout

1. Enable the agent clean-checkout behavior so a stale working copy is discarded and re-fetched.
2. Confirm the commit still exists on the remote if history was rewritten.
3. Re-run the build to fetch the current commit.

buildkite-agent start --git-clean-flags="-ffxdq" --git-fetch-flags="-v --prune"

Refresh the mirror on the agent

Delete or re-fetch the agent git mirror so it contains the latest refs before checkout.

git -C ~/.buildkite-agent/git-mirrors/acme-app fetch --prune origin

How to prevent it

• Enable clean-checkout flags so stale working copies are discarded.
• Prune and refresh agent git mirrors regularly.
• Avoid force-pushing branches that have builds in flight.

Frequently asked questions

Related guides

References

• GitHub Actions documentation