puppetlabs/puppet · error · ArgumentError

The puppet agent command does not take parameters

Error message

The puppet agent command does not take parameters

What it means

Puppet::Application::Agent#setup raises ArgumentError unless command_line.args is empty: 'puppet agent' accepts flags only, no positional parameters. Any word after 'agent' that is not an option is treated as a parameter and aborts agent startup during setup.

Source

Thrown at lib/puppet/application/agent.rb:470

  def main(daemon)
    Puppet.notice _("Starting Puppet client version %{version}") % { version: Puppet.version }
    daemon.start
  end

  # Enable all of the most common test options.
  def setup_test
    Puppet.settings.handlearg("--no-usecacheonfailure")
    Puppet.settings.handlearg("--no-splay")
    Puppet.settings.handlearg("--show_diff")
    Puppet.settings.handlearg("--no-daemonize")
    options[:verbose] = true
    Puppet[:onetime] = true
    options[:detailed_exitcodes] = true
  end

  def setup
    raise ArgumentError, _("The puppet agent command does not take parameters") unless command_line.args.empty?

    setup_test if options[:test]

    setup_logs

    exit(Puppet.settings.print_configs ? 0 : 1) if Puppet.settings.print_configs?

    Puppet::SSL::Oids.register_puppet_oids

    if options[:fqdn]
      Puppet[:certname] = options[:fqdn]
    end

    Puppet.settings.use :main, :agent, :ssl

    Puppet::Transaction::Report.indirection.terminus_class = :rest
    # we want the last report to be persisted locally
    Puppet::Transaction::Report.indirection.cache_class = :yaml

View on GitHub (pinned to e227c27540)

Solutions

1. Move the value onto a flag: puppet agent --server puppet.example.com
2. Remove all positional words after 'puppet agent'; print the full command the wrapper builds to see what snuck in
3. Quote shell expansions used in flag values so they do not split into extra arguments

Example fix

# before
puppet agent puppet.example.com

# after
puppet agent --server puppet.example.com

positional = ARGV.drop_while { |a| a.start_with?('-') } # after subcommand
unless positional.empty?
  abort 'puppet agent takes flags only — use --server <host>, not a positional host'
end

When it happens

Trigger: Running 'puppet agent puppet.example.com' (the server must be set with --server), 'puppet agent --test leftover', or a wrapper forwarding stray positional words into the agent command line.

Common situations: Muscle memory from tools that take a hostname positionally; unquoted shell variables expanding into extra words; scripts appending log paths or hostnames after 'puppet agent'.

Related errors

• Need exactly two arguments: filebucket diff <file_a> <file_b
• An action must be specified.
• Request to Puppet Forge failed. Detail: %{detail}.
• Error parsing arguments
• Please supply a parameter to perform a Hiera lookup

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