git "fatal: reference is not a tree" on checkout in CI

git was told to check out a specific commit, but that object is not in the local repository. A shallow clone (default fetch-depth 1) only fetched the tip, so an older or sibling commit the workflow references is missing.

What this error means

A checkout of a pinned SHA fails with "fatal: reference is not a tree: <sha>". It commonly hits submodule pins or a workflow that checks out a commit different from HEAD.

git

fatal: reference is not a tree: 9fceb02d0ae598e95dc970b74767f19372d61af8
Unable to checkout '9fceb02d0ae598e95dc970b74767f19372d61af8' in submodule path 'vendor/shared'

Common causes

A shallow clone did not fetch the referenced commit

With fetch-depth 1 only the tip is present. A submodule pinned to an older commit, or a checkout of a non-tip SHA, references an object that was never downloaded.

The submodule pin points at a rewritten or missing commit

A force-push in the submodule removed the exact commit the parent pins, so the object no longer exists on the remote.

How to fix it

Fetch enough history

Use full history so any referenced commit is available, and fetch submodules with it.

.github/workflows/ci.yml

- uses: actions/checkout@v4
  with:
    submodules: recursive
    fetch-depth: 0

Repoint the submodule to an existing commit

If the pinned commit was force-pushed away, update the submodule to a commit that still exists.
Commit the new gitlink in the parent repo.
Re-run so the referenced object resolves.

Terminal

git submodule update --init --recursive --depth 0

How to prevent it

Use fetch-depth: 0 when any step references a non-tip commit or submodule pin.
Avoid force-pushes that orphan commits other repos pin to.
Update submodule pins to commits that exist on the remote.