puppetlabs/puppet · error · Puppet::Error

Listing remote file buckets is not allowed

Error message

Listing remote file buckets is not allowed

What it means

The FileBucket 'file' terminus implements list (the search action) by walking the local bucket directory and matching file mtimes against a fromdate/todate window. The method refuses any request whose node or ip attribute is set (request.remote? is true), because bucket enumeration is only supported by the process that owns the bucket files. There is no server-side setting that enables remote listing, so the raise is unconditional.

Source

Thrown at lib/puppet/indirector/file_bucket_file/file.rb:47

        if request.options[:diff_with]
          other_contents_file = path_for(request.options[:bucket_path], request.options[:diff_with], 'contents')
          raise _("could not find diff_with %{diff}") % { diff: request.options[:diff_with] } unless Puppet::FileSystem.exist?(other_contents_file)
          raise _("Unable to diff on this platform") unless Puppet[:diff] != ""

          diff(Puppet::FileSystem.path_string(contents_file), Puppet::FileSystem.path_string(other_contents_file))
        else
          # TRANSLATORS "FileBucket" should not be translated
          Puppet.info _("FileBucket read %{checksum}") % { checksum: checksum }
          model.new(Puppet::FileSystem.binread(contents_file))
        end
      else
        nil
      end
    end

    def list(request)
      if request.remote?
        raise Puppet::Error, _("Listing remote file buckets is not allowed")
      end

      fromdate = request.options[:fromdate] || "0:0:0 1-1-1970"
      todate = request.options[:todate] || Time.now.strftime("%F %T")
      begin
        to = Time.parse(todate)
      rescue ArgumentError
        raise Puppet::Error, _("Error while parsing 'todate'")
      end
      begin
        from = Time.parse(fromdate)
      rescue ArgumentError
        raise Puppet::Error, _("Error while parsing 'fromdate'")
      end
      # Setting hash's default value to [], needed by the following loop
      bucket = Hash.new { [] }
      msg = ''.dup
      # Get all files with mtime between 'from' and 'to'

View on GitHub (pinned to e227c27540)

Solutions

1. SSH into the host that owns bucketdir (usually the Puppet server) and run 'puppet filebucket list --fromdate ... --todate ...' there without --remote.
2. For specific known files use 'puppet filebucket find <checksum> --remote', which is permitted remotely.
3. Enumerate the bucket directly: find "$(puppet config print bucketdir)" -name paths -newermt 'YYYY-MM-DD'.
4. Wrap the local command in SSH for scheduled remote audits; do not try to re-enable remote listing.

Example fix

# before (from a workstation)
puppet filebucket list --remote --fromdate "2024-01-01"
# Error: Listing remote file buckets is not allowed

# after (on the bucket host)
ssh puppet.example.com 'puppet filebucket list --fromdate "2024-01-01"'

# refuse to attempt a remote listing up front
target = Puppet.settings[:server]
local = [target, target.split('.').first].include?(Socket.gethostname)
raise ArgumentError, 'filebucket list must run on the bucket host' unless local
Puppet::FileBucket::File.indirection.search(key, bucket_path: Puppet.settings[:bucketdir])

When it happens

Trigger: Running 'puppet filebucket list --fromdate ... --todate ...' with the -r/--remote flag, or issuing a REST search against the file_bucket_file indirection (GET /puppet/v3/file_bucket_file/... with search semantics) from a host other than the one holding bucketdir. Any such request carries node/ip, so remote? is true and list raises Puppet::Error before date parsing even starts.

Common situations: An admin tries to audit or prune the Puppet server's file bucket from a workstation and adds --remote because filebucket find and backup accept it. CI or cleanup scripts try to enumerate bucket contents over HTTPS. Users copy 'puppet filebucket find <sum> --remote' habits into the list subcommand.

Related errors

• 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
• Failed to diff files

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