apache/pulsar · error · ParameterException

Either s3ManagedLedgerOffloadRegion or s3ManagedLedgerOffloa

Error message

Either s3ManagedLedgerOffloadRegion or s3ManagedLedgerOffloadServiceEndpoint must be set if s3 offload enabled

What it means

In set-offload-policies, when the selected driver is an S3-family driver, either an AWS region or a service endpoint must be provided. The command throws this ParameterException when both --s3ManagedLedgerOffloadRegion and the endpoint option are empty, because the S3 offloader cannot resolve a bucket location without one of them.

Source

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

        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 persistentTopic = validatePersistentTopic(topicName);

            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

Add `--s3ManagedLedgerOffloadRegion <region>` (e.g. us-east-1).
Or for S3-compatible endpoints, pass `--s3ManagedLedgerOffloadServiceEndpoint <url>` (e.g. http://minio:9000).
Confirm the driver is actually an S3 driver; if not, this requirement does not apply.

Example fix

// before
bin/pulsar-admin topics set-offload-policies my-topic --driver aws-s3 --bucket my-bucket
// after
bin/pulsar-admin topics set-offload-policies my-topic --driver aws-s3 --bucket my-bucket --s3ManagedLedgerOffloadRegion us-east-1

Defensive patterns

Strategy: validation

Validate before calling

// require region or endpoint for S3-family drivers
case "$DRIVER" in
  aws-s3|s3)
    if [ -z "$REGION" ] && [ -z "$ENDPOINT" ]; then
      echo "s3ManagedLedgerOffloadRegion or s3ManagedLedgerOffloadServiceEndpoint required"; exit 1;
    fi ;;
esac

Prevention

Store region/endpoint in env or config so S3 offload commands always have one.
For MinIO or other S3-compatible stores, always set the service endpoint.
Don't assume broker-side config substitutes for the CLI flags.

When it happens

Trigger: Running `pulsar-admin topics set-offload-policies --driver aws-s3` (or another S3 driver) without passing --s3ManagedLedgerOffloadRegion and without --s3ManagedLedgerOffloadServiceEndpoint.

Common situations: Using S3-compatible stores (MinIO, Dell ECS) and forgetting the custom endpoint; assuming region is inherited from the broker's global configuration when the CLI requires it explicitly.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

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