puppetlabs/puppet · error · ArgumentError

Invalid environment setting '%{value}'

Error message

Invalid environment setting '%{value}'

What it means

The exec type's environment parameter takes a string or array of KEY=value settings; validate requires every entry to match /\w+=/ (a word followed by '='). Entries lacking an '=' (bare 'FOO', empty strings, symbols or numbers whose Object#=~ yields nil) raise ArgumentError 'Invalid environment setting'. The match is an unanchored substring test, so 'A=1 B=2' passes as one string, but 'FOO' does not.

Source

Thrown at lib/puppet/type/exec.rb:309

        must fully qualify the command's name."

      validate do |command|
        provider.validatecmd(command)
      end
    end

    newparam(:environment) do
      desc "An array of any additional environment variables you want to set for a
        command, such as `[ 'HOME=/root', 'MAIL=root@example.com']`.
        Note that if you use this to set PATH, it will override the `path`
        attribute. Multiple environment variables should be specified as an
        array."

      validate do |values|
        values = [values] unless values.is_a? Array
        values.each do |value|
          unless value =~ /\w+=/
            raise ArgumentError, _("Invalid environment setting '%{value}'") % { value: value }
          end
        end
      end
    end

    newparam(:umask, :required_feature => :umask) do
      desc "Sets the umask to be used while executing this command"

      munge do |value|
        if value =~ /^0?[0-7]{1,4}$/
          return value.to_i(8)
        else
          raise Puppet::Error, _("The umask specification is invalid: %{value}") % { value: value.inspect }
        end
      end
    end

    newparam(:timeout) do

View on GitHub (pinned to e227c27540)

Solutions

1. Format every entry as KEY=value: environment => ['HOME=/root', 'MAIL=root@example.com']
2. When mapping a hash, join explicitly: $env = $vars.map |$k, $v| { "${k}=${v}" }
3. Drop empty/nil entries before assignment: $vars.filter |$e| { $e =~ /\w+=/ }
4. Remember PATH set here overrides the exec path parameter

Example fix

# before
exec { 'deploy': command => '/bin/deploy', environment => $env_vars } # $env_vars = ['FOO', 'BAR=1'] => ArgumentError

# after
$env_vars = {'FOO' => 'x', 'BAR' => '1'}
exec { 'deploy': command => '/bin/deploy', environment => $env_vars.map |$k, $v| { "${k}=${v}" } }

$env = $vars.map |$k, $v| { "${k}=${v}" }
# or in Ruby:
values = [values] unless values.is_a?(Array)
bad = values.reject { |v| v.is_a?(String) && v =~ /\w+=/ }
raise ArgumentError, "bad environment entries: #{bad.inspect}" unless bad.empty?

When it happens

Trigger: environment => 'FOO' (no '='), environment => ['HOME=/root', 42], environment => :PATH (Symbol), or entries derived from structured data where only the key name was joined. Also strings like '=bar' where no word character precedes the '='.

Common situations: Building environment entries from hashes and forgetting to join ('%s=%s' % [k, v]); data-driven execs taking env lists from hiera where an entry lost its value; copying docker-compose style env lists (plain names) into Puppet.

Related errors

• The umask specification is invalid: %{value}
• Invalid environment mode '%{mode_name}'
• Module %{module_name} not found in environment %{environment
• Module %{module_name} not found in environment %{environment
• No suitable tar implementation found

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