puppetlabs/puppet · error · ArgumentError

You can only have one filebucket path

Error message

You can only have one filebucket path

What it means

The filebucket type's path parameter validate rejects Arrays with 'You can only have one filebucket path' — a filebucket designates exactly one local bucket directory (or false to use a remote bucket), so multiple paths are not representable.

Source

Thrown at lib/puppet/type/filebucket.rb:75

      desc "The port on which the remote server is listening.

        This setting is _only_ consulted if the `path` attribute is set to `false`.

        If this attribute is not specified, the first entry in the `server_list`
        configuration setting is used, followed by the value of the `serverport`
        setting if `server_list` is not set."
    end

    newparam(:path) do
      desc "The path to the _local_ filebucket; defaults to the value of the
        `clientbucketdir` setting.  To use a remote filebucket, you _must_ set
        this attribute to `false`."

      defaultto { Puppet[:clientbucketdir] }

      validate do |value|
        if value.is_a? Array
          raise ArgumentError, _("You can only have one filebucket path")
        end

        if value.is_a? String and !Puppet::Util.absolute_path?(value)
          raise ArgumentError, _("Filebucket paths must be absolute")
        end

        true
      end
    end

    # Create a default filebucket.
    def self.mkdefaultbucket
      new(:name => "puppet", :path => Puppet[:clientbucketdir])
    end

    def bucket
      mkbucket unless defined?(@bucket)
      @bucket

View on GitHub (pinned to e227c27540)

Solutions

1. Set exactly one path string: `filebucket { 'main': path => '/var/lib/puppet/clientbucket' }`.
2. Fix the Hiera key to a scalar; if merge strategies produce arrays, set lookup_options merge => first.
3. For remote buckets use `path => false` plus `server => 'puppet'` — not a second path.
4. Diagnose with `puppet lookup <key> --explain` to see which layer yields the array.

Example fix

// before
filebucket { 'main': path => ['/var/b1', '/var/b2'] }

// after
filebucket { 'main': path => '/var/b1' }

// Puppet: keep the value scalar
$path = assert_type(String, $path)

def filebucket_path_ok?(v)
  v == false || v.is_a?(String)
end

When it happens

Trigger: `filebucket { 'main': path => ['/var/b1', '/var/b2'] }`; a Hiera automatic parameter lookup returning an array (list-typed data or an array merge strategy); ENC data passing multiple values into the path parameter.

Common situations: Hiera lookup merging (deep/array) turning a scalar into a list; YAML authors storing path as a list; attempting to configure local and remote buckets simultaneously instead of using path => false with server.

Related errors

• Unrecognized value for request 'merge' parameter: '%{merge}'
• Filebucket paths must be absolute
• Undefined variable '%{name}'; %{reason}
• Could not find data item %{key} in any Hiera data file and n
• Please supply a parameter to perform a Hiera lookup

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