puppetlabs/puppet · error · ArgumentError

The timeout must be a number.

Error message

The timeout must be a number.

What it means

The exec type's timeout parameter munges its value by first shifting out of an Array and then calling Float(value); an ArgumentError from that conversion is re-raised as ArgumentError 'The timeout must be a number.' (with the original backtrace attached). Valid inputs include integers, floats, and numeric strings like '300'; the munge clamps the result to a minimum of 0.0, and 0 disables the timeout.

Source

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

          return value.to_i(8)
        else
          raise Puppet::Error, _("The umask specification is invalid: %{value}") % { value: value.inspect }
        end
      end
    end

    newparam(:timeout) do
      desc "The maximum time the command should take.  If the command takes
        longer than the timeout, the command is considered to have failed
        and will be stopped. The timeout is specified in seconds. The default
        timeout is 300 seconds and you can set it to 0 to disable the timeout."

      munge do |value|
        value = value.shift if value.is_a?(Array)
        begin
          value = Float(value)
        rescue ArgumentError => e
          raise ArgumentError, _("The timeout must be a number."), e.backtrace
        end
        [value, 0.0].max
      end

      defaultto 300
    end

    newparam(:tries) do
      desc "The number of times execution of the command should be tried.
        This many attempts will be made to execute the command until an
        acceptable return code is returned. Note that the timeout parameter
        applies to each try rather than to the complete set of tries."

      munge do |value|
        if value.is_a?(String)
          unless value =~ /^\d+$/
            raise ArgumentError, _("Tries must be an integer")
          end

View on GitHub (pinned to e227c27540)

Solutions

1. Use plain seconds: timeout => 300 (integer/float) or the string '300'
2. Set 0 to disable the timeout entirely, not 'none'
3. Convert human units before applying (e.g., 1.5 * 60 in Puppet code, or keep data as numbers)
4. Validate data files: ensure profile::exec_timeout keys are numeric (hiera data linters catch quoted numbers)

Example fix

# before
exec { 'backup': command => '/usr/local/bin/backup', timeout => '2 hours' } # => ArgumentError

# after
exec { 'backup': command => '/usr/local/bin/backup', timeout => 7200 }

v = value.is_a?(Array) ? value.first : value
Float(v) rescue raise ArgumentError, 'timeout must be numeric seconds (0 disables)'

When it happens

Trigger: timeout => '5 minutes', timeout => 'none', timeout => '1m30s', or any non-numeric string. Values arriving from hiera as human units or from helpers returning duration strings all fail. Note nil (undef) raises TypeError, not this error, and arrays are tolerated by taking the first element.

Common situations: Duration syntax copied from systemd/terraform ('30s') into Puppet data; hiera values quoted with units; refactors switching an integer setting to a templated string; defaults like 'none' intended to mean no limit instead of 0.

Understand the failure class

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• Timeout waiting for exclusive lock on %{path}
• Timed out waiting for #{@resource[:name]} to transition stat
• Timed out waiting for #{@resource[:name]} to transition stat
• Command must be a String or Array<String>, got value of clas
• Invalid environment setting '%{value}'

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