{"record":{"id":"6dc05525c4d0485f","repo":"puppetlabs/puppet","slug":"the-file-mode-specification-must-be-a-string-not","errorCode":null,"errorMessage":"The file mode specification must be a string, not '#{value.class.name}'","messagePattern":"The file mode specification must be a string, not '#(.+?)'","errorType":"validation","errorClass":"Puppet::Error","httpStatus":null,"severity":"error","filePath":"lib/puppet/type/file/mode.rb","lineNumber":80,"sourceCode":"\n      See the manual page for GNU or BSD `chmod` for more details\n      on numeric and symbolic modes.\n\n      On Windows, permissions are translated as follows:\n\n      * Owner and group names are mapped to Windows SIDs\n      * The \"other\" class of users maps to the \"Everyone\" SID\n      * The read/write/execute permissions map to the `FILE_GENERIC_READ`,\n        `FILE_GENERIC_WRITE`, and `FILE_GENERIC_EXECUTE` access rights; a\n        file's owner always has the `FULL_CONTROL` right\n      * \"Other\" users can't have any permissions a file's group lacks,\n        and its group can't have any permissions its owner lacks; that is, \"0644\"\n        is an acceptable mode, but \"0464\" is not.\n    EOT\n\n    validate do |value|\n      unless value.is_a?(String)\n        raise Puppet::Error, \"The file mode specification must be a string, not '#{value.class.name}'\"\n      end\n      unless value.nil? or valid_symbolic_mode?(value)\n        raise Puppet::Error, \"The file mode specification is invalid: #{value.inspect}\"\n      end\n    end\n\n    munge do |value|\n      return nil if value.nil?\n\n      unless valid_symbolic_mode?(value)\n        raise Puppet::Error, \"The file mode specification is invalid: #{value.inspect}\"\n      end\n\n      # normalizes to symbolic form, e.g. u+a, an octal string without leading 0\n      normalize_symbolic_mode(value)\n    end\n\n    unmunge do |value|","sourceCodeStart":62,"sourceCodeEnd":98,"githubUrl":"https://github.com/puppetlabs/puppet/blob/e227c27540975c25aa22d533a52424a9d2fc886a/lib/puppet/type/file/mode.rb#L62-L98","documentation":"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.","triggerScenarios":"`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.","commonSituations":"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.","solutions":["Quote all modes: `mode => '0644'`.","In Hiera, store mode as a quoted string: `mode: '0644'`.","Convert numeric sources in the manifest: `mode => sprintf('%04o', $num)`.","Run puppet-lint in CI — it flags unquoted octal modes."],"exampleFix":"// before\nfile { '/etc/app.conf': mode => 0644 }\n\n// after\nfile { '/etc/app.conf': mode => '0644' }","handlingStrategy":"type-guard","validationCode":"// Puppet: assert the value is a string before the file resource sees it\n$mode = assert_type(String, $mode)","typeGuard":"def mode_param_ok?(v)\n  v.is_a?(String)\nend","tryCatchPattern":null,"preventionTips":["Quote every octal mode ('0644') — unquoted 0644 is Integer 420.","Quote modes in Hiera YAML as well.","Enable puppet-lint in CI to flag unquoted octal modes.","Prefer the 4-digit form '0644' for clarity."],"tags":["puppet","file","mode","octal","type-validation"],"backgroundTag":"invalid-file-mode","analyzedSha":"e227c27540975c25aa22d533a52424a9d2fc886a","analyzedAt":"2026-08-21T20:49:46.650Z","schemaVersion":2},"datasetVersion":"2026-08-21T23:17:16.201Z"}