puppetlabs/puppet · error · Puppet::Error

Failed to retrieve %{name}: %{detail}

Error message

Failed to retrieve %{name}: %{detail}

What it means

Raised by `Puppet::Configurer::Downloader#evaluate` — the component that syncs plugins, pluginfacts, and locales — when the file-copying transaction had a failed resource and `ignore_plugin_errors` is false. `trans.any_failed?` returns the first failed resource status and its first event's message is interpolated as `%{detail}`, so the real cause (a specific file failure) is embedded in the error. The run aborts before catalog application because custom facts/types/providers could not be synced.

Source

Thrown at lib/puppet/configurer/downloader.rb:23

class Puppet::Configurer::Downloader
  attr_reader :name, :path, :source, :ignore

  # Evaluate our download, returning the list of changed values.
  def evaluate
    Puppet.info _("Retrieving %{name}") % { name: name }

    files = []
    begin
      catalog.apply do |trans|
        unless Puppet[:ignore_plugin_errors]
          # Propagate the first failure associated with the transaction. The any_failed?
          # method returns the first resource status that failed or nil, not a boolean.
          first_failure = trans.any_failed?
          if first_failure
            event = (first_failure.events || []).first
            detail = event ? event.message : 'unknown'
            raise Puppet::Error, _("Failed to retrieve %{name}: %{detail}") % { name: name, detail: detail }
          end
        end

        trans.changed?.each do |resource|
          yield resource if block_given?
          files << resource[:path]
        end
      end
    rescue Puppet::Error => detail
      if Puppet[:ignore_plugin_errors]
        Puppet.log_exception(detail, _("Could not retrieve %{name}: %{detail}") % { name: name, detail: detail })
      else
        raise detail
      end
    end
    files
  end

View on GitHub (pinned to e227c27540)

Solutions

1. Read the `%{detail}` portion — it names the actual file/resource failure; fix that root cause first (permissions, mount, disk)
2. Verify reachability with `puppet agent -t --trace` and check the fileserver access log for the failing path
3. Clear the plugin cache (`rm -rf $(puppet config print libdir)`) and re-sync
4. As a temporary workaround set `ignore_plugin_errors = true` so failures log as 'Could not retrieve ...' and the run continues — accepting that custom types/facts may be missing

Example fix

# before: run aborts on any pluginsync file failure
# after (temporary workaround, puppet.conf)
[main]
ignore_plugin_errors = true   # log and continue; still fix the root cause

# fail fast if the plugin mount is servable for this environment before the run
session = Puppet.lookup(:http_session)
fs = session.route_to(:fileserver)
begin
  fs.get_file_metadatas(path: URI(Puppet[:pluginsource]).path, recurse: :false, environment: Puppet[:environment])
rescue Puppet::HTTP::ResponseError => e
  abort 'pluginsource not servable; pluginsync will fail' if e.response.code == 404
  raise
end

begin
  downloader.evaluate
rescue Puppet::Error => e
  raise unless Puppet[:ignore_plugin_errors]
  Puppet.log_exception(e, "continuing after pluginsync failure: #{e.message}")
end

When it happens

Trigger: Any pluginsync file resource failing inside `catalog.apply`: the fileserver mount for `puppet:///plugins` is missing or returns 404, permission denied on the source or the local target directory, checksum verification failure, or disk full — combined with `ignore_plugin_errors = false` (the default).

Common situations: Compile master missing the plugins mount; agent's vardir/libdir owned by root while the agent runs as non-root; SELinux/AppArmor denials; read-only filesystem; a corrupt or unreadable file inside a module's lib directory; stale plugin cache after agent upgrades.

Related errors

• Environment '%{environment}' not found on server, aborting r
• Catalog environment didn't stabilize after %{tries} fetches,
• Could not retrieve local facts: %{detail}
• Could not find type %{request_type}
• Unknown resource type %{type}

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