puppetlabs/puppet · error · Puppet::Error

Listing remote file buckets is not allowed

Error message

Listing remote file buckets is not allowed

What it means

Dipper#list enumerates filebucket contents, but only for a locally-backed Dipper (constructed with a :Path bucket directory, i.e. local? is true). When the Dipper targets a remote server (:Server given, so @rest_path is set and @local_path nil), listing raises Puppet::Error immediately: the REST filebucket API exposes no directory-listing endpoint, so Puppet forbids the attempt.

Source

Thrown at lib/puppet/file_bucket/dipper.rb:163

          of.binmode
          newcontents.stream do |source_stream|
            FileUtils.copy_stream(source_stream, of)
          end
        }
        ::File.chmod(changed, file) if changed
      else
        Puppet.err _("Could not find file with checksum %{sum}") % { sum: sum }
        return nil
      end
      newsum
    else
      nil
    end
  end

  # List Filebucket content.
  def list(fromdate, todate)
    raise Puppet::Error, _("Listing remote file buckets is not allowed") unless local?

    source_path = "#{@rest_path}#{@checksum_type}/"
    file_bucket_list = Puppet::FileBucket::File.indirection.find(
      source_path,
      :bucket_path => @local_path,
      :list_all => true,
      :fromdate => fromdate,
      :todate => todate
    )
    raise Puppet::Error, _("File not found") unless file_bucket_list

    file_bucket_list.to_s
  end

  private

  def absolutize_path(path)
    Pathname.new(path).realpath

View on GitHub (pinned to e227c27540)

Solutions

1. Run the listing on the server host against its local bucketdir (use `puppet filebucket --local list` there)
2. Or list the server's bucket directory directly over SSH/filesystem
3. If client-side listing is a hard requirement, keep a local bucket (no server setting for filebucket)

Example fix

# before (on agent, remote bucket configured)
puppet filebucket list
# after (on the filebucket server)
puppet filebucket --local list --bucketdir /opt/puppetlabs/server/data/puppetserver/bucket

raise Puppet::Error, 'listing requires a local bucket' unless dipper.local?
dipper.list(from, to)

def local_dipper?(d)
  d.respond_to?(:local?) && d.local?
end

When it happens

Trigger: `puppet filebucket list` while the filebucket is routed to a server (puppet.conf [filebucket] `server` set, no local bucket); constructing Puppet::FileBucket::Dipper.new(:Server => 'puppet.example.com', :Port => 8140) and calling #list.

Common situations: Sites that centralize backups on Puppet Server and later try to audit bucket contents from an agent node.

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/d6f24a9c553f82e3. Report an issue: GitHub.