apache/pulsar · error · ParameterException

Either s3ManagedLedgerOffloadRegion or s3ManagedLedgerOffloa

Error message

Either s3ManagedLedgerOffloadRegion or s3ManagedLedgerOffloadServiceEndpoint must be set if s3 offload enabled

What it means

For S3-family offload drivers, the CLI requires either an S3 region or a service endpoint to be configured; otherwise the SDK cannot resolve the bucket. If both --region and --service-endpoint (s3ManagedLedgerOffloadServiceEndpoint) are empty for an S3 driver, this ParameterException is thrown.

Source

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

        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");
            }
            positiveCheck("maxBlockSizeInBytes", maxBlockSizeInBytes);
            maxValueCheck("maxBlockSizeInBytes", maxBlockSizeInBytes, Integer.MAX_VALUE);
            positiveCheck("readBufferSizeInBytes", readBufferSizeInBytes);
            maxValueCheck("readBufferSizeInBytes", readBufferSizeInBytes, Integer.MAX_VALUE);

            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(","))

View on GitHub (pinned to 820761864e)

Solutions

Add --region <aws-region> (e.g. us-east-1) to the command
Alternatively add --service-endpoint <url> for custom/S3-compatible endpoints (e.g. http://minio:9000)
Confirm the driver really is S3-family; if not, a non-S3 driver may not require these flags

Example fix

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

Defensive patterns

Strategy: validation

Validate before calling

if (isS3Driver(driver) && isBlank(region) && isBlank(serviceEndpoint)) {
    throw new IllegalArgumentException("S3 offload requires --region or --service-endpoint");
}

Prevention

Always supply --region for AWS S3, --service-endpoint for MinIO/custom endpoints
Keep region/endpoint in your deployment config and pass them in wrappers
Remember CLI flags are independent of broker.conf offload settings

When it happens

Trigger: Running set-offload-policies with --driver s3 (or another isS3Driver match) while omitting both --region and --service-endpoint flags.

Common situations: Users assuming region can be inherited from environment/AWS config at CLI time; MinIO or other S3-compatible setups where users set only a bucket without an endpoint; scripts migrating from non-S3 drivers that never carried region flags.

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

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