puppetlabs/puppet · error · ArgumentError

command_line or app_name must be specified

Error message

command_line or app_name must be specified

What it means

Process.create requires at least one of :app_name or :command_line so CreateProcess has something to launch; validate_command_line raises ArgumentError('command_line or app_name must be specified') when both are nil. This fires during argument validation, before any Win32 process API is touched - the hash is structurally valid but empty of the one mandatory option.

Source

Thrown at lib/puppet/util/windows/monkey_patches/process.rb:238

      args.each do |key, val|
        key = key.to_s.to_sym
        raise ArgumentError, "invalid key '#{key}'" unless VALID_KEYS.include?(key)

        hash[key] = val
      end
    end

    def validate_startup_info
      hash[:startup_info].each do |key, val|
        key = key.to_s.to_sym
        raise ArgumentError, "invalid startup_info key '#{key}'" unless VALID_SI_KEYS.include?(key)

        si_hash[key] = val
      end
    end

    def validate_command_line
      raise ArgumentError, 'command_line or app_name must be specified' unless hash[:app_name] || hash[:command_line]
    end

    def procinfo
      @procinfo ||= PROCESS_INFORMATION.new
    end

    def hash
      @hash ||= {}
    end

    def si_hash
      @si_hash ||= {}
    end

    def app
      wide_string(hash[:app_name])
    end

View on GitHub (pinned to e227c27540)

Solutions

1. Always pass :command_line (preferred) or :app_name
2. Fail fast in your wrapper: raise ArgumentError unless opts[:command_line] || opts[:app_name]
3. Check for misspelled keys (:cmd, :command) that leave the real options unset
4. Prefer :command_line when setting only one - it does not require an absolute path or extension

Example fix

// before
Process.create(cwd: 'C:\\work')  # nothing to launch -> ArgumentError

// after
Process.create(command_line: 'rake build', cwd: 'C:\\work')

raise ArgumentError, 'command_line or app_name is required' unless args[:command_line] || args[:app_name]
Process.create(args)

begin
  info = Process.create(args)
rescue ArgumentError => e
  raise unless e.message.include?('command_line or app_name')
  raise 'spawn target missing - check config key spelling (:command_line vs :cmd)'
end

When it happens

Trigger: Process.create(cwd: 'C:\tmp') with neither :command_line nor :app_name; a builder that assigns command_line conditionally (e.g. only when a template interpolates non-empty) and silently yields nil; option hashes deep-merged where a nil command_line overrides a default.

Common situations: Wrapper functions taking an optional command that is skipped for 'default' runs; config-driven spawning where the command key is misspelled (so it lands under an invalid key or is dropped before create); test helpers calling Process.create({}).

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

• invalid key '#{key}'
• invalid startup_info key '#{key}'
• password must be specified if with_logon is used
• Invalid log level %{level}
• out_buffer is required

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