puppetlabs/puppet · error · ArgumentError

You must set the 'external_nodes' parameter to use the exter

Error message

You must set the 'external_nodes' parameter to use the external node terminus

What it means

The exec node terminus (node_terminus = exec) builds its command from the external_nodes setting, which defaults to the literal string "none". The command accessor explicitly refuses to run when the setting still equals "none", raising ArgumentError before any external node script is invoked. This is a configuration guard: the terminus is selected but the script it needs was never configured.

Source

Thrown at lib/puppet/indirector/node/exec.rb:13

# frozen_string_literal: true

require_relative '../../../puppet/node'
require_relative '../../../puppet/indirector/exec'

class Puppet::Node::Exec < Puppet::Indirector::Exec
  desc "Call an external program to get node information.  See
  the [External Nodes](https://puppet.com/docs/puppet/latest/lang_write_functions_in_puppet.html) page for more information."
  include Puppet::Util

  def command
    command = Puppet[:external_nodes]
    raise ArgumentError, _("You must set the 'external_nodes' parameter to use the external node terminus") unless command != _("none")

    command.split
  end

  # Look for external node definitions.
  def find(request)
    output = super or return nil

    # Translate the output to ruby.
    result = translate(request.key, output)

    facts = request.options[:facts].is_a?(Puppet::Node::Facts) ? request.options[:facts] : nil

    # Set the requested environment if it wasn't overridden
    # If we don't do this it gets set to the local default
    result[:environment] ||= request.environment

    create_node(request.key, result, facts)

View on GitHub (pinned to e227c27540)

Solutions

1. Set the ENC script path in the [master] section: puppet config set external_nodes /usr/local/bin/enc.sh --section master
2. Ensure the script is executable (chmod +x) and returns YAML on stdout
3. If you no longer want an ENC, switch back to the default: puppet config set node_terminus plain --section master
4. Restart puppetserver after changing these settings so the JRuby pool picks them up

Example fix

# before (puppet.conf on master)
[master]
  node_terminus = exec
# external_nodes unset -> defaults to 'none'
# => ArgumentError: You must set the 'external_nodes' parameter to use the external node terminus

# after
[master]
  node_terminus = exec
  external_nodes = /etc/puppetlabs/puppet/enc.sh

if Puppet[:node_terminus] == 'exec' && Puppet[:external_nodes] == 'none'
  raise Puppet::Error, 'node_terminus=exec requires external_nodes to be set'
end

When it happens

Trigger: Setting node_terminus = exec in puppet.conf without also setting external_nodes; or explicitly leaving external_nodes = none while expecting node facts to come from an ENC. Triggered the moment the master attempts to resolve a node (Puppet::Node.indirection.find during catalog compilation).

Common situations: Copy-pasted puppet.conf fragments that set node_terminus but omit external_nodes; disabling an ENC by resetting external_nodes to none while forgetting to revert node_terminus to plain; upgrading from legacy ENC docs without setting the script path.

Related errors

• key is a %{klass}, not a string or symbol
• Could not load external node results for %{name}: %{detail}
• Invalid terminus name %{terminus_class}
• Could not find terminus %{terminus_class} for indirection %{
• manifest_file or code_string cannot be given when configured

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