actions/checkout "Submodule path not initialized"

By Kaveh Alemi·Latchkey

checkout only fetches submodules when submodules is set. Without it, a later build that expects submodule files finds the path empty/uninitialized.

What this error means

A build fails because a submodule path is empty, or git reports the submodule path is not initialized.

fatal: Submodule path 'vendor/lib': not initialized
##[error]Submodule path not initialized

Common causes

submodules not requested

checkout ran without submodules: true, so submodule content was never fetched.

Private submodule auth missing

A private submodule needs a token that can read the other repo.

How to fix it

Request submodules (with token for private ones)

1. Set submodules: true (or recursive) on actions/checkout.
2. For private submodules, pass a token with access to those repos.
3. Re-run; submodule paths populate.

- uses: actions/checkout@v4
  with:
    submodules: recursive
    token: ${{ secrets.SUBMODULES_TOKEN }}

How to prevent it

• Set submodules on checkout whenever the build needs submodule content.
• Use a token with cross-repo read access for private submodules.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions