git "clone of ... failed" into submodule path in CI

git could not clone one submodule. This summary line follows the real cause printed just above it, which is usually an auth failure, a missing pinned commit, or an unreachable URL. Recursive updates report which path failed.

What this error means

Submodule update ends with "fatal: clone of 'https://github.com/acme/shared.git' into submodule path 'vendor/shared' failed. Failed to clone 'vendor/shared'. Retry scheduled".

git

Cloning into '/home/runner/work/app/app/vendor/shared'...
remote: Repository not found.
fatal: clone of 'https://github.com/acme/shared.git' into submodule path 'vendor/shared' failed
Failed to clone 'vendor/shared'. Retry scheduled

Common causes

Auth or access to the submodule repo

The submodule is private and the checkout credential cannot read it, so the underlying clone fails and this summary follows.

A missing pinned commit or bad URL

The pinned submodule commit was force-pushed away, or the .gitmodules URL is wrong, so the clone or checkout inside the submodule fails.

How to fix it

Read the line above and fix the real cause

Scroll up to the actual error (auth, not found, or reference is not a tree).
Fix credentials, the URL in .gitmodules, or the pinned commit accordingly.
Re-run git submodule update --init --recursive.

Fetch submodules with a covering credential and history

Use recursive submodules, a credential that can read them, and enough depth for the pin.

.github/workflows/ci.yml

- uses: actions/checkout@v4
  with:
    submodules: recursive
    fetch-depth: 0
    token: ${{ secrets.SUBMODULE_READ_PAT }}

How to prevent it

Ensure the checkout credential can read every submodule.
Keep .gitmodules URLs and pinned commits valid.
Use fetch-depth: 0 so pinned submodule commits are available.