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

Could not %{action} '%{module_name}'; no releases matching '

Error message

Could not %{action} '%{module_name}'; no releases matching '%{version}' are available from %{source}

What it means

The version-filtered variant of NoCandidateReleasesError: releases for the module exist on the source, but none satisfies the requested version string. Puppet::Module.parse_range turns --version into a SemanticPuppet range and requires at least one fetched release to fall inside it; otherwise the same Puppet::ModuleTool::Errors::NoCandidateReleasesError is raised with the requested version interpolated.

Source

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

              raise LocalChangesError,
                    :action => :upgrade,
                    :module_name => name,
                    :requested_version => results[:requested_version],
                    :installed_version => mod.version
            end
          end

          Puppet::Forge::Cache.clean

          # Ensure that there is at least one candidate release available
          # for the target package.
          available_versions = module_repository.fetch(name)
          if available_versions.empty?
            raise NoCandidateReleasesError, results.merge(:module_name => name, :source => module_repository.host)
          elsif results[:requested_version] != :latest
            requested = Puppet::Module.parse_range(results[:requested_version])
            unless available_versions.any? { |m| requested.include? m.version }
              raise NoCandidateReleasesError, results.merge(:module_name => name, :source => module_repository.host)
            end
          end

          Puppet.notice _("Downloading from %{host} ...") % { host: module_repository.host }
          if @ignore_dependencies
            graph = build_single_module_graph(name, version)
          else
            graph = build_dependency_graph(name, version)
          end

          unless forced?
            add_module_name_constraints_to_graph(graph)
          end

          installed_modules.each do |installed_module, release|
            installed_module = installed_module.tr('/', '-')
            next if installed_module == name

View on GitHub (pinned to e227c27540)

Solutions

  1. List the actual releases (Forge module page or `curl https://forgeapi.puppetlabs.com/v3/releases?module=<slug>`) and pick one that exists
  2. Omit --version entirely to take the latest release
  3. Widen the range, e.g. `--version '>= 5.0.0 < 7.0.0'` instead of an exact pin
  4. If your mirror lacks the version, sync the mirror or point module_repository at the public Forge

Example fix

# before
$ puppet module upgrade puppetlabs-stdlib --version 9.9.9
# Error: ... no releases matching '9.9.9' are available from https://forgeapi.puppetlabs.com

# after
$ puppet module upgrade puppetlabs-stdlib --version '>= 9.0.0 < 10.0.0'
Defensive patterns

Strategy: try-catch

Validate before calling

releases = Puppet::Forge.new(Puppet[:module_repository]).fetch(name)
range = Puppet::Module.parse_range(requested_version)
abort "no release of #{name} matches #{requested_version}" unless releases.any? { |r| range.include?(r.version) }

Try / catch

begin
  Puppet::ModuleTool::Applications::Upgrader.new(name, options.merge(version: pin)).run
rescue Puppet::ModuleTool::Errors::NoCandidateReleasesError
  Puppet::ModuleTool::Applications::Upgrader.new(name, options.reject { |k,_| k == :version }).run  # take latest
end

Prevention

When it happens

Trigger: Running `puppet module upgrade <name> --version 1.2.3` when 1.2.3 was never published, or a range like '>= 9.0.0' when all published versions are older, or a range excluding every available release (e.g. '4.x' when the module moved to 5.x only).

Common situations: Assuming a version exists without checking the Forge release list; pulling an old pin from documentation; a mirror lagging behind the Forge; requesting a yanked release.

Related errors

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