Introduction

This Git error usually means the repository index still thinks a path is a submodule, but .gitmodules no longer has a matching entry for it. In practice, that happens when a submodule was removed incompletely or a directory was copied around without cleaning up Git metadata. The fix is to align three places: .gitmodules, .git/config, and the index entry for the path.

Understand What Git Is Complaining About

A real submodule is represented by:

• an entry in .gitmodules
• a submodule.* section in .git/config after initialization
• a special gitlink entry in the index, usually mode 160000

If one of those pieces is missing, Git can produce the mapping error during checkout, status, submodule update, or clone-related operations.

Start by checking whether Git still tracks the path as a submodule:

git ls-files --stage | grep path/to/module

If you see mode 160000, Git still considers that path a submodule entry in the index.

Now inspect the declared submodules:

cat .gitmodules
git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$'
git config --get-regexp '^submodule\\.'

If the path appears in the index but not in .gitmodules, the repository metadata is out of sync.

Clean Up a Broken Removal

The usual cause is removing the directory from the filesystem without removing the submodule from Git properly. A clean repair looks like this:

git rm --cached path/to/module
rm -rf .git/modules/path/to/module

Then open .gitmodules and remove the matching section if it still exists:

[submodule "path/to/module"]
    path = path/to/module
    url = https://example.com/repo.git

After that, remove any leftover config entry:

git config --remove-section submodule.path/to/module

Finally, commit the cleanup:

git add .gitmodules
git commit -m "Remove stale submodule metadata"

At that point, the path is no longer treated as a submodule and the mapping error should disappear.

If the Path Should Still Be a Submodule

Sometimes the opposite is true: the repository is supposed to contain a submodule, but .gitmodules was edited incorrectly or not committed. In that case, restore the missing mapping instead of deleting the gitlink.

git submodule add https://example.com/repo.git path/to/module
git submodule sync --recursive
git submodule update --init --recursive

If the URL is already known and only .gitmodules is missing, you can recreate the entry manually, then run git submodule sync.

Distinguish a Directory from a Submodule

Developers sometimes replace a submodule with regular source files at the same path. That transition needs cleanup. If you want a normal directory there now, you must remove the gitlink entry first, commit that change, and then add the files as ordinary tracked content.

Otherwise Git still sees the path as a submodule placeholder and refuses to treat the directory like regular files.

Common Pitfalls

The most common mistake is deleting the submodule folder from disk and stopping there. That removes the files, but not the submodule metadata in the index or .git/modules.

Another mistake is editing .gitmodules without updating the index entry. The file may look correct while Git still tracks a stale gitlink under the old path.

It is also easy to forget local config. .git/config can keep submodule sections that confuse later commands, especially after manual repairs.

Finally, if the repository is shared, verify whether the broken state is only local or already committed. If the bad metadata is in the repository history, the real fix is a commit that makes .gitmodules, the index, and the intended directory structure agree again.

Summary

• The error means Git sees a submodule-like path without a matching .gitmodules mapping.
• Check whether the path is still a gitlink with git ls-files --stage.
• Remove stale metadata from the index, .gitmodules, and .git/modules if the submodule is gone.
• Recreate the .gitmodules entry and resync if the path should still be a submodule.
• Treat submodule removal as a metadata cleanup task, not just a filesystem deletion.