git submodule update fails: repository not found
Quick summary
You ran git submodule update but git cannot find or fetch one of the submodule repositories — the remote URL is wrong or the commit is missing.
Why this happens
The submodule remote URL in .gitmodules points to a private repository you lack access to or a deleted server
The superproject references a submodule commit that was force-pushed away and no longer exists on the remote
The .gitmodules file has incorrect path or URL entries after a repository migration or rename
Minimal example
git submodule update --init # fatal: repository 'https://example.com/old/repo.git' not foundgit submodule set-url sub/old https://example.com/new/repo.git
git submodule sync
git submodule update --init # succeedsUpdating the submodule URL to the new location and syncing makes git fetch from the correct remote before checking out the referenced commit.
How to diagnose
Run cat .gitmodules to inspect the configured submodule URLs and paths for correctness
Try git ls-remote <submodule-url> to verify the remote repository is accessible
Run git submodule status to see which submodules have mismatched or missing commits
How to fix
Update the submodule URL in .gitmodules with git submodule set-url <path> <new-url> then git submodule sync
Re-clone the submodule manually with git clone <url> <path> if the remote is accessible but the ref is stale
Ask the submodule maintainer to restore the referenced commit or update the superproject to point to an existing commit
How to prevent
Keep .gitmodules URLs pointing to stable, accessible repositories and update them promptly after migrations
Avoid force-pushing submodule branches that the superproject references in its gitlink entries
Related Resources
Related Lessons
- git submodule
Learn how to manage submodules.