puppetlabs/puppet · error · Puppet::ModuleTool::Errors::NotInstalledError

Could not %{action} '%{module_name}'; module is not installe

Error message

Could not %{action} '%{module_name}'; module is not installed

What it means

Raised by the Upgrader as Puppet::ModuleTool::Errors::NotInstalledError when `puppet module upgrade <name>` finds no installed module to upgrade. The upgrader flattens environment.modules_by_path and matches candidates by forge_name translated to dash form; an empty match set means the module name is not present in any directory of the active modulepath.

Source

Thrown at lib/puppet/module_tool/applications/upgrader.rb:48

        # Disallow anything that invokes md5 to avoid un-friendly termination due to FIPS
        raise _("Module upgrade is prohibited in FIPS mode.") if Puppet.runtime[:facter].value(:fips_enabled)

        name = @name.tr('/', '-')
        version = options[:version] || '>= 0.0.0'

        results = {
          :action => :upgrade,
          :requested_version => options[:version] || :latest,
        }

        begin
          all_modules = @environment.modules_by_path.values.flatten
          matching_modules = all_modules.select do |x|
            x.forge_name && x.forge_name.tr('/', '-') == name
          end

          if matching_modules.empty?
            raise NotInstalledError, results.merge(:module_name => name)
          elsif matching_modules.length > 1
            raise MultipleInstalledError, results.merge(:module_name => name, :installed_modules => matching_modules)
          end

          installed_release = installed_modules[name]

          # `priority` is an attribute of a `SemanticPuppet::Dependency::Source`,
          # which is delegated through `ModuleRelease` instances for the sake of
          # comparison (sorting). By default, the `InstalledModules` source has
          # a priority of 10 (making it the most preferable source, so that
          # already installed versions of modules are selected in preference to
          # modules from e.g. the Forge). Since we are specifically looking to
          # upgrade this module, we don't want the installed version of this
          # module to be chosen in preference to those with higher versions.
          #
          # This implementation is suboptimal, and since we can expect this sort
          # of behavior to be reasonably common in Semantic, we should probably
          # see about implementing a `ModuleRelease#override_priority` method

View on GitHub (pinned to e227c27540)

Solutions

  1. Run `puppet module list` to see the exact installed names, then upgrade using the listed forge name
  2. If it is genuinely absent, install it first: `puppet module install <author-module>`
  3. Check you are targeting the right environment: `puppet module upgrade <name> --environment <env>` or pass the correct --modulepath
  4. Watch for the uninstaller/upgrader suggestion output, which lists similarly named installed modules

Example fix

# before
$ puppet module upgrade apt   # not namespaced
# Error: Could not upgrade 'apt'; module is not installed

# after
$ puppet module list | grep apt
  puppetlabs-apt (v8.4.0)
$ puppet module upgrade puppetlabs-apt
Defensive patterns

Strategy: validation

Validate before calling

installed = env.modules_by_path.values.flatten
  .select { |m| m.forge_name && m.forge_name.tr('/', '-') == name }
abort "#{name} is not installed in this environment — use `puppet module install`" if installed.empty?

Try / catch

result = Puppet::ModuleTool::Applications::Upgrader.new(name, options).run
if result[:error] && result[:error][:oneline] =~ /module is not installed/
  Puppet::ModuleTool::Applications::Installer.new(name, options).run  # install instead
end

Prevention

When it happens

Trigger: Running `puppet module upgrade <author-module>` when no installed module's forge_name matches, e.g. wrong namespace (puppetlabs-apt vs puppet-apt), a typo, or the module living in a different environment/modulepath than the one Puppet is using.

Common situations: Forgetting the author namespace or mistyping the slug; --environment or --modulepath flags pointing elsewhere; module installed under $basemodulepath instead of the environment's modulepath; assuming `upgrade` also installs (it does not).

Related errors

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