puppetlabs/puppet · error · ArgumentError

Fileset paths must exist

Error message

Fileset paths must exist

What it means

After applying options (from a hash or a Puppet::Indirector::Request), Fileset#initialize calls valid?(path), which checks the path exists on disk. An absolute-but-nonexistent path raises ArgumentError, so filesets are never built over phantom directories.

Source

Thrown at lib/puppet/file_serving/fileset.rb:53

    end
    raise ArgumentError, _("Fileset paths must be fully qualified: %{path}") % { path: path } unless Puppet::Util.absolute_path?(path)

    @path = path

    # Set our defaults.
    self.ignore = []
    self.links = :manage
    @recurse = false
    @recurselimit = :infinite
    @max_files = 0

    if options.is_a?(Puppet::Indirector::Request)
      initialize_from_request(options)
    else
      initialize_from_hash(options)
    end

    raise ArgumentError, _("Fileset paths must exist") unless valid?(path)
    # TRANSLATORS "recurse" and "recurselimit" are parameter names and should not be translated
    raise ArgumentError, _("Fileset recurse parameter must not be a number anymore, please use recurselimit") if @recurse.is_a?(Integer)
  end

  # Return a list of all files in our fileset.  This is different from the
  # normal definition of find in that we support specific levels
  # of recursion, which means we need to know when we're going another
  # level deep, which Find doesn't do.
  def files
    files = perform_recursion
    soft_max_files = 1000

    # munged_max_files is needed since puppet http handler is keeping negative numbers as strings
    # https://github.com/puppetlabs/puppet/blob/main/lib/puppet/network/http/handler.rb#L196-L197
    munged_max_files = max_files == '-1' ? -1 : max_files

    if munged_max_files > 0 && files.size > munged_max_files
      raise Puppet::Error, _("The directory '%{path}' contains %{entries} entries, which exceeds the limit of %{munged_max_files} specified by the max_files parameter for this resource. The limit may be increased, but be aware that large number of file resources can result in excessive resource consumption and degraded performance. Consider using an alternate method to manage large directory trees") % { path: path, entries: files.size, munged_max_files: munged_max_files }

View on GitHub (pinned to e227c27540)

Solutions

1. Check the path on the exact host where the code runs: `ls -ld /srv/data` or Puppet::FileSystem.exist?(path)
2. Fix typos in the directory name
3. If the directory is created by Puppet, order the resources so the directory exists before the fileset/metadata call (require/before chains)
4. Guard at runtime and skip or create the directory first instead of letting the constructor fail

Example fix

# before
fileset = Puppet::FileServing::Fileset.new('/srv/not_created_yet')

# after
require 'fileutils'
FileUtils.mkdir_p('/srv/not_created_yet')
fileset = Puppet::FileServing::Fileset.new('/srv/not_created_yet')

unless Puppet::FileSystem.exist?(path)
  raise ArgumentError, "refusing to build fileset: #{path} missing"
end
fileset = Puppet::FileServing::Fileset.new(path, options)

begin
  Puppet::FileServing::Fileset.new(path, options)
rescue ArgumentError => e
  raise unless e.message == 'Fileset paths must exist'
  FileUtils.mkdir_p(path) if create_ok # recover only when creating is safe
  retry
end

When it happens

Trigger: Fileset.new('/srv/data') when /srv/data does not exist on this host; a typo'd directory name; a directory that is created later in the run (ordering problem); serving a path that only exists on a different node.

Common situations: Manifests or scripts referencing directories not yet provisioned; fileserver mounts pointing at a directory missing on the server; typos in absolute paths; environments where the data volume is not mounted yet.

Related errors

• Fileset paths must be fully qualified: %{path}
• Invalid option '%{option}'
• Invalid entry at %{error_location}: '%{file_text}'
• %{mount} is already mounted at %{name} at %{error_location}
• Fileset recurse parameter must not be a number anymore, plea

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