puppetlabs/puppet · error · ArgumentError

You must set the exec parameter to a fully qualified command

Error message

You must set the exec parameter to a fully qualified command

What it means

The exec terminus (used for external node classifiers and other exec-backed indirections) requires its configured command to be an Array whose first element is a fully qualified (absolute) path. If external_command[0] is not absolute — e.g. 'node.rb' or 'scripts/node.rb' — ArgumentError is raised before anything is executed.

Source

Thrown at lib/puppet/indirector/exec.rb:16

# frozen_string_literal: true

require_relative '../../puppet/indirector/terminus'
require_relative '../../puppet/util'

class Puppet::Indirector::Exec < Puppet::Indirector::Terminus
  # Look for external node definitions.
  def find(request)
    name = request.key
    external_command = command

    # Make sure it's an array
    raise Puppet::DevError, _("Exec commands must be an array") unless external_command.is_a?(Array)

    # Make sure it's fully qualified.
    raise ArgumentError, _("You must set the exec parameter to a fully qualified command") unless Puppet::Util.absolute_path?(external_command[0])

    # Add our name to it.
    external_command << name
    begin
      output = execute(external_command, :failonfail => true, :combine => false)
    rescue Puppet::ExecutionFailure => detail
      raise Puppet::Error, _("Failed to find %{name} via exec: %{detail}") % { name: name, detail: detail }, detail.backtrace
    end

    if output =~ /\A\s*\Z/ # all whitespace
      Puppet.debug { "Empty response for #{name} from #{self.name} terminus" }
      nil
    else
      output
    end
  end

  private

View on GitHub (pinned to e227c27540)

Solutions

1. Use an absolute path in the setting: external_nodes = /etc/puppetlabs/puppet/node.rb
2. When templating, expand at write time: File.expand_path(path) when generating the config
3. Confirm the file exists and is executable after fixing the path

Example fix

# before (puppet.conf)
external_nodes = node.rb
node_terminus  = exec
# => ArgumentError: You must set the exec parameter to a fully qualified command

# after
external_nodes = /etc/puppetlabs/puppet/node.rb
node_terminus  = exec

# ruby
cmd = Puppet[:external_nodes]
raise ArgumentError, 'external_nodes must be absolute' unless Puppet::Util.absolute_path?(cmd)
raise ArgumentError, 'external_nodes missing/not executable' unless File.executable?(cmd)

def absolute_executable?(cmd)
  Puppet::Util.absolute_path?(cmd) && File.executable?(cmd)
end

begin
  terminus.find(request)
rescue ArgumentError => e
  raise unless e.message.include?('fully qualified')
  Puppet[:external_nodes] = File.expand_path(Puppet[:external_nodes])
  retry
end

When it happens

Trigger: Setting the terminus's exec setting (e.g. external_nodes = node.rb or ./get_node.sh) with a relative path; templated paths that interpolate to an empty or relative value.

Common situations: puppet.conf external_nodes entry written without a leading slash that works in one cwd and breaks when the master's cwd changes; bootstrap scripts templating the path relative to a modules dir; porting configs to or from Windows where the absolute prefix differs.

Related errors

• Failed to find %{name} via exec: %{detail}
• Could not find a valid module at %{path}
• Paths must be fully qualified
• Relative paths must not be fully qualified
• Fileset paths must be fully qualified: %{path}

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