{"record":{"id":"475c501fe37f65ec","repo":"puppetlabs/puppet","slug":"provider-name-package-command-is-not-functional","errorCode":null,"errorMessage":"Provider %{name} package command is not functional on this host","messagePattern":"Provider %(.+?) package command is not functional on this host","errorType":"exception","errorClass":"Puppet::Error","httpStatus":null,"severity":"error","filePath":"lib/puppet/provider/package_targetable.rb","lineNumber":58,"sourceCode":"      end\n    end\n    package_commands\n  end\n\n  # Returns the resource command or provider command.\n\n  def resource_or_provider_command\n    resource.original_parameters[:command] || self.class.provider_command\n  end\n\n  # Targetable providers use has_command/is_optional to defer validation of provider suitability.\n  # Evaluate provider suitability here and now by validating that the command is defined and exists.\n  #\n  # cmd: the full path to the package command.\n\n  def self.validate_command(cmd)\n    unless cmd\n      raise Puppet::Error, _(\"Provider %{name} package command is not functional on this host\") % { name: name }\n    end\n    unless File.file?(cmd)\n      raise Puppet::Error, _(\"Provider %{name} package command '%{cmd}' does not exist on this host\") % { name: name, cmd: cmd }\n    end\n  end\n\n  # Return information about the package, its provider, and its (optional) command.\n\n  def to_s\n    cmd = resource[:command] || :default\n    \"#{@resource}(provider=#{self.class.name})(command=#{cmd})\"\n  end\nend\n","sourceCodeStart":40,"sourceCodeEnd":72,"githubUrl":"https://github.com/puppetlabs/puppet/blob/e227c27540975c25aa22d533a52424a9d2fc886a/lib/puppet/provider/package_targetable.rb#L40-L72","documentation":"Targetable providers (those with an optional command attribute, like the gem family) validate suitability lazily in validate_command; when the resolved command is nil - neither the resource's command attribute nor the provider's provider_command is set - the provider raises 'package command is not functional on this host'. For puppetserver_gem this means the puppetserver binary is unavailable on the node yet the resource still selected that provider.","triggerScenarios":"Declaring provider => puppetserver_gem on a host where /opt/puppetlabs/bin/puppetserver is missing or its confines (hocon feature, non-FIPS) failed so provider_command resolves nil; explicitly setting command => undef on a targetable gem resource.","commonSituations":"Applying a Puppet Server gem profile to non-server nodes; hiera data forcing the provider fleet-wide; puppetserver package removed during decommissioning while the catalog still manages its gems.","solutions":["Remove the hard-coded provider => puppetserver_gem and let provider confinement select correctly per node","If the node genuinely needs it, install the prerequisite (puppetserver package providing the binary and the hocon feature)","Set command => '<absolute path>' on the resource when the binary exists at a non-default location","Gate the resources on the node's role or facts (e.g. $facts['pe_server_version']) in the profile"],"exampleFix":"// before - forced provider on nodes that lack puppetserver\npackage { 'deep_merge':\n  ensure   => installed,\n  provider => puppetserver_gem,\n}\n// after - only on actual puppetserver nodes\nif $facts['pe_server_version'] {\n  package { 'deep_merge':\n    ensure   => installed,\n    provider => puppetserver_gem,\n  }\n}","handlingStrategy":"validation","validationCode":"# Ruby: ensure the targetable provider has a usable command before catalog application\ndef provider_command_usable?(provider_class)\n  cmd = provider_class.provider_command\n  !cmd.nil? && File.file?(cmd)\nend","typeGuard":"# True when the resource does not force a command path the host lacks\ndef targetable_resource_ready?(resource)\n  cmd = resource[:command]\n  cmd.nil? || File.file?(cmd)\nend","tryCatchPattern":null,"preventionTips":["Never force targetable providers (puppetserver_gem, gem with command) fleet-wide via hiera","Rely on provider confinement to select per node; gate server gem profiles on server facts","Install the prerequisite package (puppetserver) before managing its gems in the same role"],"tags":["targetable-provider","provider-selection","missing-command","puppetserver","gems"],"backgroundTag":"provider-command-missing","analyzedSha":"e227c27540975c25aa22d533a52424a9d2fc886a","analyzedAt":"2026-08-21T20:49:46.650Z","schemaVersion":2},"datasetVersion":"2026-08-21T23:17:16.201Z"}