When dealing with Puppet's module system, few things are more frustrating than seeing a "Could not find class" error when the module is clearly present in the correct location. Let's examine this specific case where custommod fails to load while other modules in the same directory work perfectly.

The setup appears correct at first glance:

/etc/puppet/modules/
├── base/            # Works
├── curl/            # Works
└── custommod/       # Fails
    ├── manifests/
    │   ├── init.pp
    │   └── apps.pp

Debug output shows successful imports for other modules but fails specifically for custommod:

debug: importing '/etc/puppet/modules/base/manifests/init.pp'
debug: Automatically imported base from base into production
err: Could not find class custommod for clunod-wk0130.sub.example.local

1. File Permissions

Check if the Puppet master can access the files:

sudo -u puppet ls -la /etc/puppet/modules/custommod/manifests/init.pp
# Should show readable permissions

2. Module Structure Validation

Run Puppet's module validator:

puppet module list --modulepath /etc/puppet/modules
puppet parser validate /etc/puppet/modules/custommod/manifests/init.pp

3. Environment Isolation Issues

Check if environment isolation is causing problems:

# In puppet.conf
[master]
environment_timeout = 0  # Temporarily disable caching

1. Enable Full Traces

puppet agent -t --trace --debug

2. Check Module Path Resolution

Add debug statements in site.pp:

notice("Module path: ${settings::modulepath}")
notice("Custommod path: ${module_directory}/custommod")

3. Manifest Precedence

Try explicitly declaring the path:

class { '::custommod':
  name  => 'custommod',
  paths => ['/etc/puppet/modules/custommod'],
}

After thorough debugging, the issue was found to be SELinux context mismatch. The fix:

# Restore default contexts
restorecon -Rv /etc/puppet/modules/custommod

# Alternative: Set proper context
chcon -R --reference=/etc/puppet/modules/base /etc/puppet/modules/custommod

For permanent solution, add to Puppet's SELinux policy or disable enforcement if not required:

# In custommod manifest
exec { 'fix_custommod_context':
  command => 'restorecon -Rv /etc/puppet/modules/custommod',
  unless  => 'ls -Z /etc/puppet/modules/custommod | grep -q "system_u:object_r:puppet_etc_t"',
  path    => '/usr/sbin:/usr/bin:/sbin:/bin',
}

---

When working with Puppet's module autoloading system, encountering a "Could not find class" error while the module clearly exists in the correct directory can be particularly frustrating. Let's dissect this specific case where custommod fails to load while other modules (base and curl) work perfectly.

The error manifests when running puppet agent on a new image, with the following symptoms:

• Module path verification: /etc/puppet/modules/custommod exists with proper structure
• Debug output shows successful loading of other modules
• Identical configuration works with puppet apply

The file structure appears correct:

/etc/puppet/modules/custommod/
├── manifests
│   ├── init.pp
│   └── apps.pp
└── files
    └── apps
        └── [...]

With init.pp containing:

class custommod {
}

Module Metadata Verification

First, verify the module's metadata.json (if present) contains correct naming:

{
  "name": "organization-custommod",
  "version": "1.0.0",
  "author": "YourName",
  "summary": "Custom module",
  "license": "Apache-2.0"
}

Note: Hyphens in module names can cause parsing issues in some Puppet versions.

Environment Confirmation

Check the active environment with:

puppet config print environment

And verify module path configuration:

puppet config print modulepath --section master

Permission Check

Run as root to verify it's not a permission issue:

sudo puppet agent -t --debug

Direct Class Loading Test

Attempt to directly load the class definition:

puppet apply -e 'include custommod' --debug

Module Path Cleanup

Sometimes stale cached data causes issues. Clean and regenerate:

puppet master --compile NODE_NAME --clean
service puppetmaster restart

Explicit Import

Try explicitly importing the module in site.pp:

import 'custommod'
node /clunod-wk\d+\.sub\.example\.local/ {
  include custommod
  # ...
}

Environment Isolation Test

Create a test environment to isolate the issue:

mkdir -p /etc/puppet/environments/test/modules
cp -r /etc/puppet/modules/custommod /etc/puppet/environments/test/modules/
puppet agent -t --environment test

For deeper investigation, enable full debugging:

puppet agent -t --debug --trace --verbose

And check Puppet Server logs (if applicable):

tail -f /var/log/puppetlabs/puppetserver/puppetserver.log

After applying fixes, verify module loading with:

puppet module list

And specifically check your module's availability:

puppet describe --list | grep custommod