Dealing with error TF401019 when using submodules in Azure Pipelines

I'm in the process om migrating a whole bunch of builds from TeamCity to Azure DevOps and the entire process is automated. (I'm writing a blogpost on this, stay tuned if you are interested in this). Today, one of the builds that I'm migrating, gave me an error when I did a test. It struck me a bit as "a strange situation" as the error occurred when checking out. This can be seen below:

When drilling down in the pipeline and focusing on the actual error, I saw this:

TF401019: The Git repository with name or identifier repo-name-of-submodule does not exist or you do not have permissions for the operation you are attempting.

At first sight, I assumed that it had to do something with the link between the git repo and the linked submodule. S, there are a few easy-candidates for troubleshooting:

1. Check if the submodules are (also) checked out when checking out the main repo. (This was ok since the log talks about the submodule...)
2. Check if there is an issue with the .submodules file in your main repo. (Again, the chance for this was pretty low since the submodule was also linked during development and during the builds in the context of TeamCity)

Since these weren't an issue, I had to start looking further. I found one post on a forum that said that there was (in their case) an issue with the permissions of the build service account on this repo. Again, this was really unlikely since we try not to change those permissions too much...

And then, for some reason I started clicking around in the settings of the Azure DevOps project. and under the "Pipelines" section, there seems to be an entire set of settings (1) that can be managed with toggles. (2)

After investigating a bit, nr3 stood out. This one basically says that you give the build process only permissions to access repo's that have been referenced explicitly. Since a submodule is referenced "indirectly" from a pipelines "point of view", I can understand that activating this setting causes your checkout process to fail... (as the pipeline process just doesn't have the permissions to access the submodule)

The result is that I disabled this flag as can be seen below:

and from this point on, the pipeline process just worked like a charm!

If you fall on this one day, then I hope that it will help you! It's a hard one to find if you don't know that this setting exists! 😃

Edit: I also wrote another post on Git (Azure Repos) submodules, so if you are experiencing issues in this area, then I encourage you to take a look at this post: What you should think about when running Azure Pipelines with Git and submodules