git submodules - could not get a repository handle for submodule

Question

Git submodule support seems to be very buggy. I tried switching branches in a worktree and now I keep getting this error:

fatal: could not get a repository handle for submodule 'the_submodule'

What does it mean exactly? What is a repository handle?

Answer 1

The way I got around this was to manually clean up and reinit my problematic submodule:

git submodule deinit the_submodule
git submodule init the_submodule
git submodule update the_submodule

Note that at this time (early 2023), unfortunately, git worktree does not play nice with submodules. The manpage for git-worktree lists under BUGS:

Multiple checkout in general is still experimental, and the support for submodules is incomplete. It is NOT recommended to make multiple checkouts of a superproject.

(emphasis mine)

Edit: You can also continue git operations even with the broken submodule state by disabling the submodule.recurse option (default off), either through git config or on a per-command basis with git -c submodule.recurse=no subcommand ...

Answer 2

What fixed it for me was a combination of these answers; it seems things can become corrupt (even with a branch change) and simply removing them and re-adding them works without having to pull down the whole repo.

rm -rf .git/modules/the_submodule/ the_submodule/;
git submodule init "the_submodule";
git submodule update