dev@local: ~/project — git
dev@local~/project$git submodule add
Cloning into 'libs/shared-module'...
error: submodule repository exists
Diagnostics Translation
Git cannot add a submodule because a Git repository already occupies that path.
waiting for resolution...
LowVersion 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 means the target folder already behaves like its own repository, so Git will not silently replace it with a submodule mapping.
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 add
Downloading a zip file of a library, unzipping it into your project, and then trying to run on that folder
$.gitmodules
Re-adding a submodule after deleting its entry in but forgetting to delete the physical folder
Technical Background
01
Git is protecting the existing repository. You cannot link a submodule over a folder that already thinks it is an independent Git project.
02
The existing folder must usually be deleted, or its internal `.git` folder removed, before the submodule command can cleanly take over.
Underlying Causes
You cloned a repository into a subfolder manually instead of using `git submodule add`
A previous submodule was improperly removed, leaving the `.git` directory behind
You are trying to map a submodule to a path that contains uncommitted work
Frequently Asked Questions
Use the command `git submodule add <url> <path>`. Git will automatically clone the repository and configure the mapping in one step.