{"record":{"id":"05865fab07501f63","repo":"puppetlabs/puppet","slug":"fileset-paths-must-exist","errorCode":null,"errorMessage":"Fileset paths must exist","messagePattern":"Fileset paths must exist","errorType":"exception","errorClass":"ArgumentError","httpStatus":null,"severity":"error","filePath":"lib/puppet/file_serving/fileset.rb","lineNumber":53,"sourceCode":"    end\n    raise ArgumentError, _(\"Fileset paths must be fully qualified: %{path}\") % { path: path } unless Puppet::Util.absolute_path?(path)\n\n    @path = path\n\n    # Set our defaults.\n    self.ignore = []\n    self.links = :manage\n    @recurse = false\n    @recurselimit = :infinite\n    @max_files = 0\n\n    if options.is_a?(Puppet::Indirector::Request)\n      initialize_from_request(options)\n    else\n      initialize_from_hash(options)\n    end\n\n    raise ArgumentError, _(\"Fileset paths must exist\") unless valid?(path)\n    # TRANSLATORS \"recurse\" and \"recurselimit\" are parameter names and should not be translated\n    raise ArgumentError, _(\"Fileset recurse parameter must not be a number anymore, please use recurselimit\") if @recurse.is_a?(Integer)\n  end\n\n  # Return a list of all files in our fileset.  This is different from the\n  # normal definition of find in that we support specific levels\n  # of recursion, which means we need to know when we're going another\n  # level deep, which Find doesn't do.\n  def files\n    files = perform_recursion\n    soft_max_files = 1000\n\n    # munged_max_files is needed since puppet http handler is keeping negative numbers as strings\n    # https://github.com/puppetlabs/puppet/blob/main/lib/puppet/network/http/handler.rb#L196-L197\n    munged_max_files = max_files == '-1' ? -1 : max_files\n\n    if munged_max_files > 0 && files.size > munged_max_files\n      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 }","sourceCodeStart":35,"sourceCodeEnd":71,"githubUrl":"https://github.com/puppetlabs/puppet/blob/e227c27540975c25aa22d533a52424a9d2fc886a/lib/puppet/file_serving/fileset.rb#L35-L71","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check the path on the exact host where the code runs: `ls -ld /srv/data` or Puppet::FileSystem.exist?(path)","Fix typos in the directory name","If the directory is created by Puppet, order the resources so the directory exists before the fileset/metadata call (require/before chains)","Guard at runtime and skip or create the directory first instead of letting the constructor fail"],"exampleFix":"# before\nfileset = Puppet::FileServing::Fileset.new('/srv/not_created_yet')\n\n# after\nrequire 'fileutils'\nFileUtils.mkdir_p('/srv/not_created_yet')\nfileset = Puppet::FileServing::Fileset.new('/srv/not_created_yet')","handlingStrategy":"validation","validationCode":"unless Puppet::FileSystem.exist?(path)\n  raise ArgumentError, \"refusing to build fileset: #{path} missing\"\nend\nfileset = Puppet::FileServing::Fileset.new(path, options)","typeGuard":null,"tryCatchPattern":"begin\n  Puppet::FileServing::Fileset.new(path, options)\nrescue ArgumentError => e\n  raise unless e.message == 'Fileset paths must exist'\n  FileUtils.mkdir_p(path) if create_ok # recover only when creating is safe\n  retry\nend","preventionTips":["Order manifests so directories are ensured before anything walks them","Smoke-test served paths on the target host before enabling mounts","Log missing paths distinctly from relative-path mistakes (different errors, adjacent lines)"],"tags":["puppet","fileset","file-not-found","argumenterror","ruby"],"backgroundTag":"file-not-found","analyzedSha":"e227c27540975c25aa22d533a52424a9d2fc886a","analyzedAt":"2026-08-21T20:49:46.650Z","schemaVersion":2},"datasetVersion":"2026-08-21T23:17:16.201Z"}