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

Could not %{action} '%{module_name}' (%{version}); downgrade

Error message

Could not %{action} '%{module_name}' (%{version}); downgrades are not allowed

What it means

Raised by the Upgrader as Puppet::ModuleTool::Errors::DowngradingUnsupportedError when the resolved release's version is lower than the installed version and --force was not passed. The `upgrade` action intentionally refuses to move backwards; downgrades must be explicit.

Source

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

                  :directory => mod.path,
                  :metadata => mod.metadata
          end

          child = releases.find { |x| x.name == name }

          unless forced?
            if child.version == results[:installed_version]
              versions = graph.dependencies[name].map(&:version)
              newer_versions = versions.select { |v| v > results[:installed_version] }

              raise VersionAlreadyInstalledError,
                    :module_name => name,
                    :requested_version => results[:requested_version],
                    :installed_version => results[:installed_version],
                    :newer_versions => newer_versions,
                    :possible_culprits => installed_modules_source.fetched.reject { |x| x == name }
            elsif child.version < results[:installed_version]
              raise DowngradingUnsupportedError,
                    :module_name => name,
                    :requested_version => results[:requested_version],
                    :installed_version => results[:installed_version]
            end
          end

          Puppet.info _("Preparing to upgrade ...")
          releases.each(&:prepare)

          Puppet.notice _('Upgrading -- do not interrupt ...')
          releases.each do |release|
            installed = installed_modules[release.name]
            if installed
              release.install(Pathname.new(installed.mod.modulepath))
            else
              release.install(dir)
            end
          end

View on GitHub (pinned to e227c27540)

Solutions

1. Do the rollback explicitly: `puppet module uninstall <name>` then `puppet module install <name> --version <older>`
2. Or reinstall over it in one step: `puppet module install <name> --version <older> --force`
3. If the downgrade is intended via upgrade, add --force: `puppet module upgrade <name> --version <older> --force`
4. Double-check the version pin in your Puppetfile/scripts so future upgrades request a newer version

Example fix

# before
$ puppet module upgrade puppetlabs-stdlib --version 8.6.0   # installed 9.1.0
# Error: Could not upgrade 'puppetlabs-stdlib' (8.6.0); downgrades are not allowed

# after
$ puppet module install puppetlabs-stdlib --version 8.6.0 --force

mod = env.modules.find { |m| m.forge_name && m.forge_name.tr('/', '-') == name }
if mod && mod.version && options[:version]
  target = SemanticPuppet::Version.parse(options[:version].to_s)
  if target < SemanticPuppet::Version.parse(mod.version)
    # downgrade path: install --force, not upgrade
    Puppet::ModuleTool::Applications::Installer.new(name, options).run
  end
end

begin
  Puppet::ModuleTool::Applications::Upgrader.new(name, options).run
rescue Puppet::ModuleTool::Errors::DowngradingUnsupportedError
  Puppet::ModuleTool::Applications::Installer.new(name, options.merge(force: true)).run  # explicit downgrade
end

When it happens

Trigger: Running `puppet module upgrade <name> --version <older>` (or letting a dependency graph resolve to a lower version) when the installed version is higher, e.g. installed 9.1.0 and requesting --version 8.5.0.

Common situations: Rolling back a module after a bad release by using upgrade --version with an older number; a constrained graph resolving to an older release than the one installed; CI templates that pin an old version string.

Related errors

• Could not %{action} '%{module_name}'; module is not installe
• Could not %{action} '%{module_name}'; module appears in mult
• Could not %{action} '%{module_name}'; module has had changes
• Could not %{action} '%{module_name}'; no releases are availa
• Could not %{action} '%{module_name}'; no releases matching '

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