puppetlabs/puppet · error · Puppet::Module::MissingModule

Module %{module_name} not found in environment %{environment

Error message

Module %{module_name} not found in environment %{environment_name}.

What it means

Puppet::InfoService::PlanInformationService.plan_data resolves the environment (Puppet.lookup(:environments).get! raises separately if missing), then looks up the module with Puppet::Module.find. If no module of that name exists in the environment's modulepath, it raises Puppet::Module::MissingModule with this message. This powers 'puppet plan show' and Puppet Server plan APIs (Bolt orchestration surface).

Source

Thrown at lib/puppet/info_service/plan_information_service.rb:22

  require_relative '../../puppet/module'

  def self.plans_per_environment(environment_name)
    # get the actual environment object, raise error if the named env doesn't exist
    env = Puppet.lookup(:environments).get!(environment_name)
    env.modules.map do |mod|
      mod.plans.map do |plan|
        { :module => { :name => plan.module.name }, :name => plan.name }
      end
    end.flatten
  end

  def self.plan_data(environment_name, module_name, plan_name)
    # raise EnvironmentNotFound if applicable
    Puppet.lookup(:environments).get!(environment_name)

    pup_module = Puppet::Module.find(module_name, environment_name)
    if pup_module.nil?
      raise Puppet::Module::MissingModule, _("Module %{module_name} not found in environment %{environment_name}.") %
                                           { module_name: module_name, environment_name: environment_name }
    end

    plan = pup_module.plans.find { |t| t.name == plan_name }
    if plan.nil?
      raise Puppet::Module::Plan::PlanNotFound.new(plan_name, module_name)
    end

    begin
      plan.validate
      { :metadata => plan.metadata, :files => plan.files }
    rescue Puppet::Module::Plan::Error => err
      { :metadata => nil, :files => [], :error => err.to_h }
    end
  end
end

View on GitHub (pinned to e227c27540)

Solutions

1. Confirm the module directory exists and matches the case: ls $(puppet config print environmentpath)/<env>/modules | grep -i <module>
2. Verify modulepath resolution for that environment: puppet config print modulepath --section master --environment <env>
3. Redeploy the control repo / r10k environment so the plan's module is present
4. Pass the environment that actually contains the module when calling plan_data

Example fix

# before
Puppet::InfoService::PlanInformationService.plan_data('production', 'apache', 'restart')
# => Puppet::Module::MissingModule: Module apache not found in environment production.

# after: module lives under 'site' path in env config
# environment.conf: modulepath = site:modules:$basemodulepath
Puppet::InfoService::PlanInformationService.plan_data('production', 'apache', 'restart')
# with modules/apache/plans/restart.pp deployed under the 'site' dir

env = Puppet.lookup(:environments).get!(environment_name)
mod = Puppet::Module.find(module_name, environment_name)
raise Puppet::Module::MissingModule, "#{module_name} missing from #{environment_name}" if mod.nil?
result = Puppet::InfoService::PlanInformationService.plan_data(environment_name, module_name, plan_name)

begin
  data = Puppet::InfoService::PlanInformationService.plan_data(env, mod, plan)
rescue Puppet::Module::MissingModule
  data = nil  # or fall back to a known-good environment containing the plan
end

When it happens

Trigger: Calling Puppet::InfoService::PlanInformationService.plan_data('production', 'apache', 'restart') when the apache module is absent from production's modulepath, when the module name is mispelled or wrongly cased (module lookup is case-sensitive on directory names), or when environment.conf modulepath points elsewhere than expected.

Common situations: Bolt plan invocations where the plan's module was not deployed to the PE environment; querying a plan in the wrong environment; module directory renamed without updating invocations; Control-repo deploy gaps leaving modulepath empty.

Related errors

• Module %{module_name} not found in environment %{environment
• Invalid environment mode '%{mode_name}'
• Could not find %{path} on disk
• No suitable tar implementation found
• The environment directory '%{env_dir}' does not exist

AI-assisted analysis of puppetlabs/puppet@e227c27540 (2026-08-21). Data as JSON: /api/errors/7a1ab29baddd0115. Report an issue: GitHub.