TL;DR: The Quick Fix
You’re likely seeing this error because Git’s index—the internal staging area—thinks a folder is a submodule, but it cannot find a matching URL in your .gitmodules file. You have two ways to resolve this depending on your goal.
Option A: Re-register the submodule
If the folder is supposed to be a submodule, tell Git where the remote repository lives. Replace libs/ui with your specific path:
# If Git says the path already exists in the index, clear it first:
git rm --cached libs/ui
# Now properly add it back:
git submodule add https://github.com/username/repo.git libs/ui
Option B: Convert it to a regular folder
Did you accidentally add a folder that contains its own .git history? You can strip the submodule metadata and track it like a normal directory instead:
git rm --cached libs/ui
rm -rf libs/ui/.git # Delete the internal Git history
git add libs/ui
git commit -m "Convert broken submodule to regular directory"
Why is Git complaining?
Git submodules rely on a delicate three-way handshake between your .gitmodules file, the .git/config file, and the Git Index. The fatal: No url found error triggers when that handshake fails.
Specifically, your Git Index contains a "gitlink." This is a special 160-bit entry that points to a specific commit in another repository. When you run a command like git submodule update, Git looks at that gitlink and then checks .gitmodules to find the download source. If the URL is missing or the names do not match exactly, Git gives up.
Common scenarios that cause this mess include:
- Messy Merges: A merge conflict in
.gitmoduleswas resolved by deleting the wrong lines. - Manual Deletions: A developer deleted the submodule entry from the text file but forgot to remove it from Git's internal tracking.
- Nested Repos: You copied a library from another project (like
vendor/bootstrap) that still had its own.gitfolder hidden inside.
Proven Repair Methods
1. Manual Repair of .gitmodules
Sometimes the easiest fix is to just write the configuration yourself. Open .gitmodules in your editor. Ensure the block looks exactly like this, matching your folder path:
[submodule "libs/ui"]
path = libs/ui
url = https://github.com/example/ui-library.git
Precision is key here. The string in [submodule "name"] must align with your project structure. Once you save the file, run these commands to sync the state:
git submodule sync
git submodule update --init --recursive
2. Purging the "Phantom" Submodule
If you never intended for a folder to be a submodule, Git is likely confused by a legacy .git file. To fix this, you must remove the path from the index without deleting the actual files. Use git rm --cached folder/path, but be careful not to add a trailing slash. This tells Git to stop treating the directory as a separate repository link.
3. Resetting the Submodule Cache
If your configuration looks correct but Git still throws errors, the local cache might be corrupted. You can force a reset by removing the entry from the index and re-adding it. This refreshes the gitlink and ensures the .git/config file is updated to match your .gitmodules.
Verify the Health of Your Repo
After applying a fix, run these three checks to make sure everything is back to normal:
- Status Check: Run
git submodule status. You should see a commit hash followed by the path. If no error appears, you're in the clear. - Config Check: Run
cat .git/config. Verify that the[submodule]sections there match what you have in.gitmodules. - Deep Update: Run
git submodule update --init --recursive. This is the ultimate test. If it finishes without a fatal error, the project is fully repaired.