apache/pulsar · error · ParameterException

Either s3ManagedLedgerOffloadRegion or s3ManagedLedgerOffloa

Error message

Either s3ManagedLedgerOffloadRegion or s3ManagedLedgerOffloadServiceEndpoint must be set if s3 offload enabled

What it means

The pulsar-admin namespaces set-offload-policies command requires S3-compatible offload drivers (aws-s3, s3, google-cloud-storage in S3 mode, etc.) to know where to send data. If both the region (s3ManagedLedgerOffloadRegion) and service endpoint (s3ManagedLedgerOffloadServiceEndpoint) are empty, the driver cannot be constructed, so the CLI rejects the parameters up front with a ParameterException.

Source

Thrown at pulsar-client-tools/src/main/java/org/apache/pulsar/admin/cli/CmdNamespaces.java:2351

        public boolean isS3Driver(String driver) {
            if (StringUtils.isEmpty(driver)) {
                return false;
            }
            return driver.equalsIgnoreCase(driverNames.get(0)) || driver.equalsIgnoreCase(driverNames.get(1));
        }

        @Override
        void run() throws PulsarAdminException {
            String namespace = validateNamespace(namespaceName);

            if (!driverSupported(driver)) {
                throw new ParameterException("The driver " + driver + " is not supported, "
                        + "(Possible values: " + String.join(",", driverNames) + ").");
            }

            if (isS3Driver(driver) && Strings.isNullOrEmpty(region) && Strings.isNullOrEmpty(endpoint)) {
                throw new ParameterException(
                        "Either s3ManagedLedgerOffloadRegion or s3ManagedLedgerOffloadServiceEndpoint must be set"
                                + " if s3 offload enabled");
            }

            OffloadedReadPriority offloadedReadPriority = OffloadPoliciesImpl.DEFAULT_OFFLOADED_READ_PRIORITY;
            if (this.offloadReadPriorityStr != null) {
                try {
                    offloadedReadPriority = OffloadedReadPriority.fromString(this.offloadReadPriorityStr);
                } catch (Exception e) {
                    throw new ParameterException("--offloadedReadPriority parameter must be one of "
                            + Arrays.stream(OffloadedReadPriority.values())
                            .map(OffloadedReadPriority::toString)
                            .collect(Collectors.joining(","))
                            + " but got: " + this.offloadReadPriorityStr, e);
                }
            }

            OffloadPolicies offloadPolicies = OffloadPoliciesImpl.create(driver, region, bucket, endpoint,

View on GitHub (pinned to 820761864e)

Solutions

1. Pass --region with the bucket's AWS region, e.g. --region us-west-2
2. Or pass --service-endpoint pointing at the S3-compatible endpoint, e.g. --service-endpoint http://s3.amazonaws.com or a MinIO endpoint
3. For MinIO/other S3-compatible storage, supply --service-endpoint; for plain AWS S3, supplying --region is usually enough
4. Switch to a driver that does not require region/endpoint if storage is not S3-compatible (e.g. azureblob, gcs)

Example fix

// before
pulsar-admin namespaces set-offload-policies --driver s3 --bucket my-bucket
// after
pulsar-admin namespaces set-offload-policies --driver s3 --bucket my-bucket --region us-west-2

if (isS3Driver(driver) && (region == null || region.isEmpty()) && (endpoint == null || endpoint.isEmpty())) {
    throw new IllegalArgumentException("Set --region or --service-endpoint for S3 offload");
}

try {
    admin.namespaces().setOffloadPolicies(ns, policies);
} catch (org.apache.pulsar.client.admin.PulsarAdminException e) {
    // handle missing S3 region/endpoint config
}

When it happens

Trigger: Running `pulsar-admin namespaces set-offload-policies --driver s3` (or another S3-driver) without passing --region or --service-endpoint, or passing empty strings for both.

Common situations: Operators copying offload config from a non-S3 example (e.g. azureblob/abs driver options), forgetting the region when migrating to AWS, or setting offload driver in broker.conf but omitting S3 region/endpoint when mirroring it via the admin CLI.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Timeout during managed ledger terminate
• You must specify tls-trust-store-type, tls-trust-store and t
• --offloadedReadPriority parameter must be one of %s but got:
• Timeout during delete operation
• Timeout during close operation

AI-assisted analysis of apache/pulsar@820761864e (2026-09-06). Data as JSON: /api/errors/ab9852948001cceb. Report an issue: GitHub.