puppetlabs/puppet · error · ArgumentError

Filebucket paths must be absolute

Error message

Filebucket paths must be absolute

What it means

The filebucket path validate also requires String values to satisfy Puppet::Util.absolute_path? — the bucket directory must be unambiguously located, so relative paths raise 'Filebucket paths must be absolute'.

Source

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

        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
    end

    private

View on GitHub (pinned to e227c27540)

Solutions

1. Use a fully qualified path: '/var/lib/puppet/clientbucket' or 'C:/ProgramData/PuppetLabs/bucket'.
2. Build from a known base: "${vardir}/clientbucket" so the result is absolute.
3. For remote-only buckets set path => false instead of a filesystem path.
4. Expand tildes/variables before assignment when sourcing from user input.

Example fix

// before
filebucket { 'main': path => 'bucket' }

// after
filebucket { 'main': path => '/var/lib/puppet/clientbucket' }

# Ruby
fail('filebucket path must be absolute (or false)') unless path == false || (path.is_a?(String) && Puppet::Util.absolute_path?(path))

def absolute_bucket_path?(v)
  v == false || (v.is_a?(String) && Puppet::Util.absolute_path?(v))
end

When it happens

Trigger: `path => 'bucket'`, `path => './bucket'`, `path => '~/bucket'`; Windows forms missing a drive letter; values built from relative variables that were never expanded.

Common situations: Reusing relative paths from application configs; tilde shortcuts that absolute_path? rejects; drive-relative Windows paths; typos dropping the leading slash.

Related errors

• You can only have one filebucket path
• Need exactly two arguments: filebucket diff <file_a> <file_b
• Could not back up %{file}: %{detail}
• Diff is not supported on this platform
• Please provide a file or checksum to diff with

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