puppetlabs/puppet · error · Puppet::Error

The file mode specification must be a string, not '#{value.c

Error message

The file mode specification must be a string, not '#{value.class.name}'

What it means

The file type's mode property validates that its value is a String. Puppet DSL parses unquoted 0644 as an octal Integer literal (decimal 420), so `mode => 0644` fails validation with "The file mode specification must be a string, not 'Integer'". Modes must be quoted octal strings or symbolic mode strings.

Source

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

      See the manual page for GNU or BSD `chmod` for more details
      on numeric and symbolic modes.

      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|

View on GitHub (pinned to e227c27540)

Solutions

1. Quote all modes: `mode => '0644'`.
2. In Hiera, store mode as a quoted string: `mode: '0644'`.
3. Convert numeric sources in the manifest: `mode => sprintf('%04o', $num)`.
4. Run puppet-lint in CI — it flags unquoted octal modes.

Example fix

// before
file { '/etc/app.conf': mode => 0644 }

// after
file { '/etc/app.conf': mode => '0644' }

// Puppet: assert the value is a string before the file resource sees it
$mode = assert_type(String, $mode)

def mode_param_ok?(v)
  v.is_a?(String)
end

When it happens

Trigger: `mode => 0644` (or 1644, 0440, ...) unquoted in a manifest — the lexer yields Integer; Hiera YAML `mode: 0644` unquoted (YAML also reads it as an octal integer); passing an Integer from Ruby code into the resource.

Common situations: Porting shell/Ansible habits where bare 0644 is natural; generated manifests emitting raw numbers; Hiera data written by hand without quotes — the classic Puppet mode gotcha.

Related errors

• The file mode specification is invalid: #{value.inspect}
• puppet.tasks/unparseable-metadata
• Expected PCallableType or PVariantType thereof, got %{type_c
• Expected block_param name to be a Symbol, got %{name_class}
• Argument to 'return_type' must be a String reference to a Pu

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