git submodules - could not get a repository handle for submodule

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?

2 Answers

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 ...

I had A similar question arise and needed the clarification that @Timmmm provided with Lore Kernel Link regarding the issue twice. As for "what it means", it seems that it means that your local repository has a reference to a legacy name for a submodule, and a new name for a submodule, and when those do not align it can cause a conflict.

As for "what is a repository handle", I think that is just the repository location name in the root/.git/modules/ for modules, and it is in use in a repository even if the submodule that it should be in reference to has been deinit'd for a change. The ordering from the Lore Kernel Link seems to indicate that it is caused in the way git handles submodules and a path forward to prevent such a user experience is not yet decided.

For anyone happening upon this thread and looking to solve the issue, the suggestion in the link to remove the .git/module/ did work for me as it did the poster. Huge shout out to @Timmmm as I have been on this for about 6 months and only just found this solution. Unlike the suggestion to just use commands without the recurse, I was unable to get into a good state without the extra steps.