puppetlabs/puppet · error · ArgumentError

invalid key '#{key}'

Error message

invalid key '#{key}'

What it means

Process.create validates every top-level option key against VALID_KEYS (app_name, command_line, inherit, creation_flags, cwd, environment, startup_info, thread_inherit, process_inherit, close_handles, with_logon, domain, password) and raises ArgumentError('invalid key ...') for anything else. Keys are normalized with to_s.to_sym, so string keys are fine - the error fires only for names outside the whitelist.

Source

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

    def initialize_defaults
      @hash = {
        app_name: nil,
        creation_flags: 0,
        close_handles: true
      }
      @si_hash = nil
      @procinfo = nil
    end

    def validate_args(args)
      raise TypeError, 'hash keyword arguments expected' unless args.is_a?(Hash)
    end

    def validate_keys(args)
      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

View on GitHub (pinned to e227c27540)

Solutions

1. Spell keys exactly as in the whitelist: app_name command_line inherit creation_flags cwd environment startup_info thread_inherit process_inherit close_handles with_logon domain password
2. Move console/GUI options (show_window etc.) into the startup_info sub-hash
3. Filter foreign option hashes before forwarding: opts.slice(*VALID_KEYS) style

Example fix

// before
Process.create(commandline: 'dir', env: 'A=1')  # both keys invalid

// after
Process.create(command_line: 'dir', environment: 'A=1')

VALID_KEYS = %i[app_name command_line inherit creation_flags cwd environment
               startup_info thread_inherit process_inherit close_handles with_logon
               domain password].freeze
unknown = args.keys.map { |k| k.to_s.to_sym } - VALID_KEYS
raise ArgumentError, "unknown Process.create keys: #{unknown.join(', ')}" unless unknown.empty?

begin
  info = Process.create(args)
rescue ArgumentError => e
  raise unless e.message =~ /invalid key/
  raise "check spelling against VALID_KEYS: #{e.message}"
end

When it happens

Trigger: Passing typo'd or unsupported options like :commandline, :show_window (belongs in startup_info), :timeout, :env (should be :environment), or options from other process libraries (e.g. win32-process gem docs or POSIX spawn options like :unsetenv_others).

Common situations: Copy-pasting option hashes from win32-process examples or Stack Overflow that include keys this patched API dropped; renaming refactors (:cmd -> stale callers); merging user-supplied option hashes without filtering.

Related errors

• invalid startup_info key '#{key}'
• command_line or app_name must be specified
• 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/b6c9ea0fa36c1764. Report an issue: GitHub.