Skip to content

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

✗ Broken code
git submodule update --init  # fatal: repository 'https://example.com/old/repo.git' not found
✓ Fixed code
git submodule set-url sub/old https://example.com/new/repo.git
git submodule sync
git submodule update --init  # succeeds

Updating 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 Glossary

Related Lessons

← Back to language