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

'%{module_name}' (%{version}) requested; '%{module_name}' (%

Error message

'%{module_name}' (%{version}) requested; '%{module_name}' (%{installed_version}) already installed

What it means

Installer raises Puppet::ModuleTool::AlreadyInstalledError when the module is already installed, --force was not given, and the installed version does not satisfy the requested version range (if it did satisfy, the installer would return :noop instead). The error carries installed_version, requested_version, and local_changes (from Checksummer) so the CLI can advise using `puppet module upgrade` or --force. `puppet module install` never changes an installed version; it only installs what is missing.

Source

Thrown at lib/puppet/module_tool/applications/installer.rb:80

        begin
          if !@local_tarball && name !~ /-/
            raise InvalidModuleNameError.new(module_name: @name, suggestion: "puppetlabs-#{@name}", action: :install)
          end

          installed_module = installed_modules[name]
          if installed_module
            unless forced?
              if Puppet::Module.parse_range(version).include? installed_module.version
                results[:result] = :noop
                results[:version] = installed_module.version
                return results
              else
                changes = begin
                  Checksummer.run(installed_modules[name].mod.path)
                rescue
                  []
                end
                raise AlreadyInstalledError,
                      :module_name => name,
                      :installed_version => installed_modules[name].version,
                      :requested_version => options[:version] || :latest,
                      :local_changes => changes
              end
            end
          end

          @install_dir.prepare(name, options[:version] || 'latest')
          results[:install_dir] = @install_dir.target

          unless @local_tarball && @ignore_dependencies
            Puppet.notice _("Downloading from %{host} ...") % {
              host: mask_credentials(module_repository.host)
            }
          end

          if @ignore_dependencies

View on GitHub (pinned to e227c27540)

Solutions

Use `puppet module upgrade <author>-<name>` (optionally with --version) when you want a newer version than installed.
Uninstall first (`puppet module uninstall`) then install the exact version desired.
Add --force to install to overwrite/downgrade regardless of the installed version (mind local changes).
Omit or widen --version so the requested range includes the installed version, yielding a no-op instead of an error.

Example fix

# before
puppet module install puppetlabs-stdlib --version 5.0.0   # 4.25.0 installed

# after
puppet module uninstall puppetlabs-stdlib && puppet module install puppetlabs-stdlib --version 5.0.0
# or: puppet module upgrade puppetlabs-stdlib --version 5.0.0

Defensive patterns

Strategy: try-catch

Validate before calling

installed = environment.modules.find { |m| m.forge_name == slug }
if installed
  requested = Puppet::Module.parse_range(version || '>= 0')
  exit 0 if requested.include?(installed.version) # no-op like the installer
end

Try / catch

begin
  Puppet::ModuleTool::Applications::Installer.new(name, options).run
rescue Puppet::ModuleTool::AlreadyInstalledError => e
  # e.multiline_options has installed_version / local_changes
  run_upgrade_or_force(name)
end

Prevention

Use `puppet module upgrade` (or r10k/Puppetfile) as the standard way to change versions; reserve install for absent modules.
Make install steps idempotent: check `puppet module list` first and skip when the desired version range is satisfied.
In automation, catch AlreadyInstalledError and treat it as success when the installed version is acceptable.

When it happens

Trigger: Running `puppet module install puppetlabs-stdlib` (or with a --version range) when site-modules/stdlib exists at a version outside that range — e.g. installed 4.25.0 and requesting '>= 5.0.0 < 6.0.0', or requesting a specific older version than what is present. Raised at installer.rb:80 from the installed_module branch.

Common situations: Pinning versions in Puppetfile after a module was already installed at another version; re-running install after manually editing metadata.json's version; trying to 'reinstall' or downgrade via install instead of upgrade; local modifications present making the hint mention local changes.

Related errors

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