{"record":{"id":"207b03e4fbf6b721","repo":"puppetlabs/puppet","slug":"could-not-list-gems-detail-207b03","errorCode":null,"errorMessage":"Could not list gems: %{detail}","messagePattern":"Could not list gems: %(.+?)","errorType":"exception","errorClass":"Puppet::Error","httpStatus":null,"severity":"error","filePath":"lib/puppet/provider/package/puppetserver_gem.rb","lineNumber":64,"sourceCode":"      command_options << '--remote'\n    end\n\n    if options[:source]\n      command_options << '--source' << options[:source]\n    end\n\n    if options[:justme]\n      gem_regex = '\\A' + options[:justme] + '\\z'\n      command_options << gem_regex\n    end\n\n    if options[:local]\n      list = execute_rubygems_list_command(command_options)\n    else\n      begin\n        list = puppetservercmd(command_options)\n      rescue Puppet::ExecutionFailure => detail\n        raise Puppet::Error, _(\"Could not list gems: %{detail}\") % { detail: detail }, detail.backtrace\n      end\n    end\n\n    # When `/tmp` is mounted `noexec`, `puppetserver gem list` will output:\n    # *** LOCAL GEMS ***\n    # causing gemsplit to output:\n    # Warning: Could not match *** LOCAL GEMS ***\n    gem_list = list\n               .lines\n               .select { |x| x =~ /^(\\S+)\\s+\\((.+)\\)/ }\n               .map { |set| gemsplit(set) }\n\n    if options[:justme]\n      gem_list.shift\n    else\n      gem_list\n    end\n  end","sourceCodeStart":46,"sourceCodeEnd":82,"githubUrl":"https://github.com/puppetlabs/puppet/blob/e227c27540975c25aa22d533a52424a9d2fc886a/lib/puppet/provider/package/puppetserver_gem.rb#L46-L82","documentation":"The puppetserver_gem provider executes 'puppetserver gem list --remote' (with any source option) and re-raises as Puppet::Error 'Could not list gems' carrying the underlying execution detail when the command exits non-zero. It means Puppet could not enumerate gems in the Puppet Server JRuby environment - typically the puppetserver CLI is broken or the remote gem source was unreachable.","triggerScenarios":"Any package resource with provider => puppetserver_gem (gemlist runs during prefetch/query with local: false) on a host where /opt/puppetlabs/bin/puppetserver fails: no network egress to rubygems.org, proxy misconfiguration, puppetserver not installed, or source => pointing at a dead gem repository.","commonSituations":"Air-gapped nodes without a gem mirror; typo'd or unavailable source URL; puppetserver package removed but the catalog still manages its gems; slow JVM startup or timeouts on the puppetserver CLI.","solutions":["Read the %{detail} text - it contains the exit status/stderr of the underlying command; run 'puppetserver gem list --remote' manually as root to reproduce","Fix network/proxy egress to the gem source, or point source at an internal mirror (pass '--clear-sources' via install_options if only that mirror should be used)","Verify puppetserver is installed at /opt/puppetlabs/bin/puppetserver and 'puppetserver gem list' succeeds","If this node should not manage server-side gems, remove the puppetserver_gem resources from its role"],"exampleFix":"// before\npackage { 'deep_merge':\n  ensure   => '1.2.1',\n  provider => puppetserver_gem,\n  source   => 'https://rubygems.org',\n}\n// after - internal mirror reachable from the node\npackage { 'deep_merge':\n  ensure   => '1.2.1',\n  provider => puppetserver_gem,\n  source   => 'https://gems.internal.example.com',\n}","handlingStrategy":"retry","validationCode":"# Ruby: verify the gem source is reachable before the run manages puppetserver gems\nrequire 'net/https'\nrequire 'uri'\ndef gem_source_reachable?(url, timeout = 10)\n  uri = URI(url)\n  http = Net::HTTP.new(uri.host, uri.port)\n  http.use_ssl = (uri.scheme == 'https')\n  http.open_timeout = timeout\n  http.get(uri.request_uri).is_a?(Net::HTTPSuccess)\nrescue StandardError\n  false\nend","typeGuard":null,"tryCatchPattern":"retries ||= 0\nbegin\n  gems = Puppet::Type.type(:package).provider(:puppetserver_gem).gemlist(local: false)\nrescue Puppet::Error => e\n  if (retries += 1) <= 3 && e.message =~ /Could not list gems/\n    sleep(2**retries)\n    retry\n  end\n  raise\nend","preventionTips":["Configure an internal gem mirror and point source at it on air-gapped nodes","Verify 'puppetserver gem list' works as root during node provisioning","Monitor egress to rubygems.org and JVM startup health of the puppetserver CLI"],"tags":["puppetserver","gems","rubygems","network","jruby","package-provider"],"backgroundTag":"package-repository-unreachable","analyzedSha":"e227c27540975c25aa22d533a52424a9d2fc886a","analyzedAt":"2026-08-21T20:49:46.650Z","schemaVersion":2},"datasetVersion":"2026-08-21T23:17:16.201Z"}