dev@local: ~/project — git
dev@local~/project$git submodule update --init
Cloning into 'libs/shared-module'...
error: no submodule mapping found in gitmodules
Diagnostics Translation
Git found a submodule reference without a matching configuration entry.
waiting for resolution...
MediumVersion Control System
Reviewed for reference consistency: April 11, 2026
Code is Safe
SECUREGit has paused the operation to protect your code. No data has been lost or corrupted.
What To Know
This points to a mismatch between a submodule path Git encountered and the parent repository metadata that should describe it.
Where Did It Fail?
Working Tree
Your local files
add
Staging Index
Prepared changes
commit
Local Repo
Commit history
push/fetch
Remote Server
GitHub/GitLab
The error involves the internal Git database or commit history structure.
Commands That Trigger This
$git submodule update --init
Running on a poorly merged branch
$.gitmodules
Pulling changes from a coworker who deleted manually
Technical Background
01
Submodules require two pieces of data to work: a special commit pointer in the parent tree, and a URL mapping in the `.gitmodules` file.
02
If they fall out of sync, Git cannot pull the required external code.
Underlying Causes
Manually deleting the `.gitmodules` file while keeping the submodule folder
A broken merge that kept a submodule hash but dropped the configuration
Manually cloning a repository inside another repository without using `git submodule add`
Frequently Asked Questions
Because submodule state lives in parent-repository metadata as well as in the visible folder. Removing only the directory does not always remove the stale relationship Git still sees.