puppetlabs/puppet · error · ArgumentError

Fileset recurse parameter must not be a number anymore, plea

Error message

Fileset recurse parameter must not be a number anymore, please use recurselimit

What it means

Historically (pre-2.6) Puppet allowed `recurse => <integer>` to mean 'recurse N levels deep'. Modern Fileset keeps depth in recurselimit and expects recurse to be boolean; if the options hash leaves @recurse as an Integer, initialize raises ArgumentError with a migration hint. This is a deliberate API-compatibility tripwire, not a runtime failure.

Source

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

    @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 }
    elsif munged_max_files == 0 && files.size > soft_max_files
      Puppet.warning _("The directory '%{path}' contains %{entries} entries, which exceeds the default soft limit %{soft_max_files} and may cause excessive resource consumption and degraded performance. To remove this warning set a value for `max_files` parameter or consider using an alternate method to manage large directory trees") % { path: path, entries: files.size, soft_max_files: soft_max_files }

View on GitHub (pinned to e227c27540)

Solutions

1. Replace the numeric recurse with `recurse => true` (or `virtual`) plus `recurselimit => N` at the same depth
2. If you feed option hashes from external sources, munge integer recurse into recurse/recurselimit before constructing the Fileset
3. Search manifests and data for `recurse\s*=>\s*[0-9]` to find all occurrences

Example fix

# before (manifest)
file { '/etc/app':
  ensure  => directory,
  source  => 'puppet:///modules/app/etc',
  recurse => 1,
}

# after
file { '/etc/app':
  ensure        => directory,
  source        => 'puppet:///modules/app/etc',
  recurse       => true,
  recurselimit  => 1,
}

# Munge legacy integer recurse before constructing a Fileset
def munge_recurse(opts)
  opts = opts.dup
  if opts[:recurse].is_a?(Integer)
    opts[:recurselimit] = opts.delete(:recurse)
    opts[:recurse] = true
  end
  opts
end

# Detect the deprecated shape before it reaches Puppet
def legacy_recurse?(opts)
  opts.is_a?(Hash) && opts[:recurse].is_a?(Integer)
end

begin
  Puppet::FileServing::Fileset.new(path, opts)
rescue ArgumentError => e
  raise unless e.message.include?('recurse parameter must not be a number')
  opts = { recurse: true, recurselimit: opts[:recurse] }
  retry
end

When it happens

Trigger: Passing `Puppet::FileServing::Fileset.new('/x', recurse: 2)`; reusing legacy manifests or serialized option hashes written for Puppet < 2.6 that carry numeric recurse values; forwarding unfiltered request options into a Fileset.

Common situations: Very old module code or snippets copied from ancient wiki/blog posts; tools that deserialize stored fileset options from an old Puppet version; migrations off Puppet 0.2x/2.x infrastructure.

Related errors

• Fileset paths must be fully qualified: %{path}
• Fileset paths must exist
• The directory '%{path}' contains %{entries} entries, which e
• Invalid option '%{option}'
• Relative paths must not be fully qualified

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