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

Could not %{action} '%{module_name}'; no releases are availa

Error message

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

What it means

Raised by the Upgrader as Puppet::ModuleTool::Errors::NoCandidateReleasesError when module_repository.fetch(name) returns an empty list, i.e. the configured module source (module_repository host, normally the Puppet Forge API) offers zero releases for that name. The message includes the host so you can tell whether the wrong repository was consulted.

Source

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

            rescue
              []
            end
            if mod.has_metadata? && !changes.empty?
              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

View on GitHub (pinned to e227c27540)

Solutions

Confirm the module exists on the source you are querying: open https://forge.puppet.com/modules/<name> or curl the API of your configured host
Check `puppet config print module_repository` and fix the setting if upgrades should hit the public Forge
If the module was renamed, upgrade under its new slug (and update dependents' metadata)
For locally packaged modules, skip upgrade and reinstall the tarball: `puppet module install ./pkg.tar.gz --force`

Example fix

# before
$ puppet module upgrade puppet-example
# Error: ... no releases are available from https://forgeapi.puppetlabs.com

# after (module was renamed)
$ puppet module uninstall puppet-example
$ puppet module install puppetlabs-example

Defensive patterns

Strategy: try-catch

Validate before calling

# Cheap pre-flight against the same source the upgrader uses
require 'puppet/forge'
releases = Puppet::Forge.new(Puppet[:module_repository]).fetch(name)
abort "no releases for #{name} on #{Puppet[:module_repository]}" if releases.empty?

Try / catch

begin
  result = Puppet::ModuleTool::Applications::Upgrader.new(name, options).run
rescue Puppet::ModuleTool::Errors::NoCandidateReleasesError => e
  log "source #{Puppet[:module_repository]} has no releases for #{name}; falling back to local tarball install"
  Puppet::ModuleTool::Applications::Installer.new("./pkg/#{name}.tar.gz", options).run
end

Prevention

Verify module slugs exist on your configured repository before adding them to Puppetfiles
If using a private mirror, monitor its sync lag against the public Forge
Keep module_repository explicit in puppet.conf so failures name the right host

When it happens

Trigger: Running `puppet module upgrade <name>` after Puppet::Forge::Cache.clean when the Forge API returns no releases: module renamed or removed from the Forge, a custom module_repository in puppet.conf pointing at a mirror that lacks the module, or a name that never existed on that host.

Common situations: Modules renamed during the puppetlabs- rebrand; private Forge mirrors (Pulp, Artifactory proxy) not synced or missing the module; typo in the slug; DNS/hosts entry sending forgeapi traffic to the wrong internal host; module distributed only as a local tarball.

Related errors

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