This week, when writing some custom Puppet modules, I was getting the following error when trying to use them:

Could not find class <class> for <node> on <node>

I could not for the life of me figure out what the problem was – the module was in the correct place, with the correct name and layout.

I finally realised it was a problem with the metadata.json file in the root of the module’s directory. It turns out that if there’s a syntax error in this file, Puppet will refuse to load the module without letting you know why. And it’s a known bug.

In my case it wasn’t even a syntax error that was the problem – it was caused by one of the required fields being missing from the manifest. For reference, the PuppetLabs docs specify the required fields for the metadata.json file.