puppetlabs/puppet · error · Puppet::Error

The file mode specification is invalid: #{value.inspect}

Error message

The file mode specification is invalid: #{value.inspect}

What it means

The mode property's validate block requires String values to pass valid_symbolic_mode? — either an octal digit string of 3–4 digits (only 0–7, optionally with a leading setuid/setgid/sticky digit) like '0644' or '1777', or symbolic notation like 'u=rw,g=r' / 'a+x'. Anything else raises 'The file mode specification is invalid: <inspect>'.

Source

Thrown at lib/puppet/type/file/mode.rb:83

      On Windows, permissions are translated as follows:

      * Owner and group names are mapped to Windows SIDs
      * The "other" class of users maps to the "Everyone" SID
      * The read/write/execute permissions map to the `FILE_GENERIC_READ`,
        `FILE_GENERIC_WRITE`, and `FILE_GENERIC_EXECUTE` access rights; a
        file's owner always has the `FULL_CONTROL` right
      * "Other" users can't have any permissions a file's group lacks,
        and its group can't have any permissions its owner lacks; that is, "0644"
        is an acceptable mode, but "0464" is not.
    EOT

    validate do |value|
      unless value.is_a?(String)
        raise Puppet::Error, "The file mode specification must be a string, not '#{value.class.name}'"
      end
      unless value.nil? or valid_symbolic_mode?(value)
        raise Puppet::Error, "The file mode specification is invalid: #{value.inspect}"
      end
    end

    munge do |value|
      return nil if value.nil?

      unless valid_symbolic_mode?(value)
        raise Puppet::Error, "The file mode specification is invalid: #{value.inspect}"
      end

      # normalizes to symbolic form, e.g. u+a, an octal string without leading 0
      normalize_symbolic_mode(value)
    end

    unmunge do |value|
      # return symbolic form or octal string *with* leading 0's
      display_mode(value) if value
    end

View on GitHub (pinned to e227c27540)

Solutions

1. Use a 3–4 digit octal string containing only 0–7: '0644', '0755', '1777'.
2. Or use symbolic mode: 'u=rw,go=r', 'g+w'.
3. Re-check values copied from `ls -l` output for spaces and unsupported notation.
4. Generate programmatically with sprintf('%04o', n) instead of hand-typing.

Example fix

// before (ls -l style, rejected)
file { '/usr/local/bin/tool': mode => 'rwxr-xr-x' }

// after
file { '/usr/local/bin/tool': mode => '0755' }

// Puppet
unless $mode =~ Pattern[/\A[0-7]{3,4}\z/] {
  fail("invalid mode '${mode}' — use '0644' or symbolic like 'u=rw,go=r'")
}

def valid_file_mode?(v)
  return false unless v.is_a?(String)
  v.match?(/\A[0-7]{3,4}\z/) || v.match?(/\A[ugoa]*[-+=][rwxXsto]*(,[ugoa]*[-+=][rwxXsto]*)*\z/)
end

When it happens

Trigger: `mode => '0999'` or '888' (9/8 are not octal digits); '64' (too short); 'rwxr-xr-x' (ls -l display form, not supported); strings with stray characters or trailing spaces like '0644 ' after copy-paste.

Common situations: Pasting the display form from `ls -l` into manifests; decimal-digit habits from chmod usage; template output carrying whitespace; mixing up Windows ACL strings with POSIX modes.

Related errors

• The file mode specification must be a string, not '#{value.c
• The umask specification is invalid: %{value}
• Could not back up; will not remove
• Could not read #{ftype} #{resource.title}: #{detail}
• Cannot create #{@resource[:path]}; parent directory #{parent

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