{"record":{"id":"aa5eb9164a0fb5c9","repo":"puppetlabs/puppet","slug":"the-file-mode-specification-is-invalid-value-in","errorCode":null,"errorMessage":"The file mode specification is invalid: #{value.inspect}","messagePattern":"The file mode specification is invalid: #(.+?)","errorType":"validation","errorClass":"Puppet::Error","httpStatus":null,"severity":"error","filePath":"lib/puppet/type/file/mode.rb","lineNumber":83,"sourceCode":"\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|\n      # return symbolic form or octal string *with* leading 0's\n      display_mode(value) if value\n    end","sourceCodeStart":65,"sourceCodeEnd":101,"githubUrl":"https://github.com/puppetlabs/puppet/blob/e227c27540975c25aa22d533a52424a9d2fc886a/lib/puppet/type/file/mode.rb#L65-L101","documentation":"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>'.","triggerScenarios":"`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.","commonSituations":"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.","solutions":["Use a 3–4 digit octal string containing only 0–7: '0644', '0755', '1777'.","Or use symbolic mode: 'u=rw,go=r', 'g+w'.","Re-check values copied from `ls -l` output for spaces and unsupported notation.","Generate programmatically with sprintf('%04o', n) instead of hand-typing."],"exampleFix":"// before (ls -l style, rejected)\nfile { '/usr/local/bin/tool': mode => 'rwxr-xr-x' }\n\n// after\nfile { '/usr/local/bin/tool': mode => '0755' }","handlingStrategy":"type-guard","validationCode":"// Puppet\nunless $mode =~ Pattern[/\\A[0-7]{3,4}\\z/] {\n  fail(\"invalid mode '${mode}' — use '0644' or symbolic like 'u=rw,go=r'\")\n}","typeGuard":"def valid_file_mode?(v)\n  return false unless v.is_a?(String)\n  v.match?(/\\A[0-7]{3,4}\\z/) || v.match?(/\\A[ugoa]*[-+=][rwxXsto]*(,[ugoa]*[-+=][rwxXsto]*)*\\z/)\nend","tryCatchPattern":null,"preventionTips":["Never paste ls -l output as a mode value.","Only digits 0-7 are legal in octal mode strings.","Use symbolic modes ('g+w') for partial changes.","Generate modes with sprintf('%04o', n) when computing them."],"tags":["puppet","file","mode","octal","symbolic-mode"],"backgroundTag":"invalid-file-mode","analyzedSha":"e227c27540975c25aa22d533a52424a9d2fc886a","analyzedAt":"2026-08-21T20:49:46.650Z","schemaVersion":2},"datasetVersion":"2026-08-21T23:17:16.201Z"}