puppetlabs/puppet · error · Puppet::Error

An empty mode string is illegal

Error message

An empty mode string is illegal

What it means

Raised by Puppet::Util::SymbolicMode.symbolic_mode_to_int when the mode argument is nil or the empty string. The parser refuses to compute a file mode from nothing rather than silently applying mode 0.

Source

Thrown at lib/puppet/util/symbolic_file_mode.rb:53

    # We need to treat integers as octal numbers.
    #
    # "A numeric mode is from one to four octal digits (0-7), derived by adding
    # up the bits with values 4, 2, and 1. Omitted digits are assumed to be
    # leading zeros."
    case value
    when Numeric
      value.to_s(8)
    when /^0?[0-7]{1,4}$/
      value.to_i(8).to_s(8) # strip leading 0's
    else
      value
    end
  end

  def symbolic_mode_to_int(modification, to_mode = 0, is_a_directory = false)
    if modification.nil? or modification == ''
      raise Puppet::Error, _("An empty mode string is illegal")
    elsif modification =~ /^[0-7]+$/
      return modification.to_i(8)
    elsif modification =~ /^\d+$/
      raise Puppet::Error, _("Numeric modes must be in octal, not decimal!")
    end

    fail _("non-numeric current mode (%{mode})") % { mode: to_mode.inspect } unless to_mode.is_a?(Numeric)

    original_mode = {
      's' => (to_mode & 0o7000) >> 9,
      'u' => (to_mode & 0o0700) >> 6,
      'g' => (to_mode & 0o0070) >> 3,
      'o' => (to_mode & 0o0007) >> 0,
      # Are there any execute bits set in the original mode?
      'any x?' => (to_mode & 0o0111) != 0
    }
    final_mode = {
      's' => original_mode['s'],

View on GitHub (pinned to e227c27540)

Solutions

1. Set an explicit mode such as mode => '0644'.
2. If the mode is optional, guard the resource or calling code so the mode is only passed when it has a value.
3. Fix the Hiera/lookup data so the mode variable is populated.

Example fix

# before (mode_var is undef/empty)
file { '/etc/app.conf': mode => $mode_var }

# after
file { '/etc/app.conf': mode => pick($mode_var, '0644') }

raise ArgumentError, 'mode must be a non-empty string' if mode.nil? || mode.to_s.empty?
Puppet::Util::SymbolicMode.symbolic_mode_to_int(mode)

def valid_mode_input?(m)
  m.is_a?(String) && !m.empty?
end

When it happens

Trigger: symbolic_mode_to_int('') or symbolic_mode_to_int(nil); in manifest terms, a file resource whose mode property resolves to '' or undef (e.g. mode => $var where the variable is empty or undef interpolated to an empty string).

Common situations: A Hiera lookup key feeding the mode parameter is missing; manifest variables that are conditionally set; templates that render an empty mode value.

Related errors

• Numeric modes must be in octal, not decimal!
• File modes must be numbers
• Missing action
• X only works with the '+' operator
• One or more file(s) specified did not exist: %{files}

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