{"record":{"id":"fca8a86c4e97285c","repo":"puppetlabs/puppet","slug":"failed-to-retrieve-name-detail","errorCode":null,"errorMessage":"Failed to retrieve %{name}: %{detail}","messagePattern":"Failed to retrieve %(.+?): %(.+?)","errorType":"exception","errorClass":"Puppet::Error","httpStatus":null,"severity":"error","filePath":"lib/puppet/configurer/downloader.rb","lineNumber":23,"sourceCode":"\nclass Puppet::Configurer::Downloader\n  attr_reader :name, :path, :source, :ignore\n\n  # Evaluate our download, returning the list of changed values.\n  def evaluate\n    Puppet.info _(\"Retrieving %{name}\") % { name: name }\n\n    files = []\n    begin\n      catalog.apply do |trans|\n        unless Puppet[:ignore_plugin_errors]\n          # Propagate the first failure associated with the transaction. The any_failed?\n          # method returns the first resource status that failed or nil, not a boolean.\n          first_failure = trans.any_failed?\n          if first_failure\n            event = (first_failure.events || []).first\n            detail = event ? event.message : 'unknown'\n            raise Puppet::Error, _(\"Failed to retrieve %{name}: %{detail}\") % { name: name, detail: detail }\n          end\n        end\n\n        trans.changed?.each do |resource|\n          yield resource if block_given?\n          files << resource[:path]\n        end\n      end\n    rescue Puppet::Error => detail\n      if Puppet[:ignore_plugin_errors]\n        Puppet.log_exception(detail, _(\"Could not retrieve %{name}: %{detail}\") % { name: name, detail: detail })\n      else\n        raise detail\n      end\n    end\n    files\n  end\n","sourceCodeStart":5,"sourceCodeEnd":41,"githubUrl":"https://github.com/puppetlabs/puppet/blob/e227c27540975c25aa22d533a52424a9d2fc886a/lib/puppet/configurer/downloader.rb#L5-L41","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Read the `%{detail}` portion — it names the actual file/resource failure; fix that root cause first (permissions, mount, disk)","Verify reachability with `puppet agent -t --trace` and check the fileserver access log for the failing path","Clear the plugin cache (`rm -rf $(puppet config print libdir)`) and re-sync","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"],"exampleFix":"# before: run aborts on any pluginsync file failure\n# after (temporary workaround, puppet.conf)\n[main]\nignore_plugin_errors = true   # log and continue; still fix the root cause","handlingStrategy":"fallback","validationCode":"# fail fast if the plugin mount is servable for this environment before the run\nsession = Puppet.lookup(:http_session)\nfs = session.route_to(:fileserver)\nbegin\n  fs.get_file_metadatas(path: URI(Puppet[:pluginsource]).path, recurse: :false, environment: Puppet[:environment])\nrescue Puppet::HTTP::ResponseError => e\n  abort 'pluginsource not servable; pluginsync will fail' if e.response.code == 404\n  raise\nend","typeGuard":null,"tryCatchPattern":"begin\n  downloader.evaluate\nrescue Puppet::Error => e\n  raise unless Puppet[:ignore_plugin_errors]\n  Puppet.log_exception(e, \"continuing after pluginsync failure: #{e.message}\")\nend","preventionTips":["Keep agent vardir/libdir ownership aligned with the agent user","Set ignore_plugin_errors=true only deliberately, knowing custom types may be missing that run","Clear the plugin cache after agent upgrades to avoid stale-file checksum failures"],"tags":["pluginsync","downloader","file-transaction","puppet-agent"],"backgroundTag":"pluginsync-failure","analyzedSha":"e227c27540975c25aa22d533a52424a9d2fc886a","analyzedAt":"2026-08-21T20:49:46.650Z","schemaVersion":2},"datasetVersion":"2026-08-21T23:17:16.201Z"}