puppetlabs/puppet · error · ArgumentError

Invalid file option '%{parameter}'

Error message

Invalid file option '%{parameter}'

What it means

In puppet.conf-style files, a setting line may carry a {...} file-options block parsed by Puppet::Settings::ConfigFile#extract_fileinfo (e.g. `$privatekeydir { owner = puppet, mode = 750 }`). Only owner, mode, and group are permitted; a `name = value` pair inside the braces whose param is anything else raises ArgumentError 'Invalid file option'.

Source

Thrown at lib/puppet/settings/config_file.rb:133

      raise Puppet::Settings::ParseError.new(detail.message, file, setting.line_number, detail)
    end
  end

  def empty_section
    { :_meta => {} }
  end

  def extract_fileinfo(string)
    result = {}
    value = string.sub(/\{\s*([^}]+)\s*\}/) do
      params = ::Regexp.last_match(1)
      params.split(/\s*,\s*/).each do |str|
        if str =~ /^\s*(\w+)\s*=\s*(\w+)\s*$/
          param = ::Regexp.last_match(1).intern
          value = ::Regexp.last_match(2)
          result[param] = value
          unless [:owner, :mode, :group].include?(param)
            raise ArgumentError, _("Invalid file option '%{parameter}'") % { parameter: param }
          end

          if param == :mode and value !~ /^\d+$/
            raise ArgumentError, _("File modes must be numbers")
          end
        else
          raise ArgumentError, _("Could not parse '%{string}'") % { string: string }
        end
      end
      ''
    end
    result[:value] = value.sub(/\s*$/, '')
    result
  end
end

View on GitHub (pinned to e227c27540)

Solutions

1. Keep only owner = <name>, mode = <digits>, and group = <name> inside {...} blocks.
2. Manage anything else (ensure, backup, selignored) with a normal file resource, not config-file braces.
3. Remove the invalid pair and re-parse the file with Puppet::Settings::ConfigFile to confirm.

Example fix

# before (puppet.conf)
vardir = /opt/puppet { owner = puppet, backup = true }

# after
vardir = /opt/puppet { owner = puppet, mode = 750 }

str.scan(/\{\s*([^}]+)\s*\}/).flatten.each do |block|
  block.split(/\s*,\s*/).each do |pair|
    m = pair.match(/^\s*(\w+)\s*=\s*(\w+)\s*$/)
    param = m && m[1].to_sym
    raise ArgumentError, "invalid file option #{param} in #{pair}" unless %i[owner mode group].include?(param)
  end
end

begin
  Puppet::Settings::ConfigFile.parse_file(file, text, [])
rescue ArgumentError => e
  raise unless e.message.include?('Invalid file option')
  Puppet.err("only owner/mode/group allowed inside {...}: #{e.message}")
  raise
end

When it happens

Trigger: Writing `vardir = /opt/puppet { owner = puppet, backup = true }` (backup not allowed); attempting ensure, create, path, or selrange inside the braces; copying docs that show unsupported per-setting file attributes.

Common situations: Users trying to manage more file attributes than Puppet supports per-setting; old 2.x-era documentation showing options modern Puppet rejects; hand-merged config files during upgrades.

Related errors

• Could not parse '%{string}'
• Global option %{option} does not exist in Puppet.settings
• Attempt to assign a value to unknown setting %{name}
• File modes must be numbers
• Cannot disable unrecognized warning types '%{invalid}'. Vali

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