{"record":{"id":"d6dcbed2e0b9cdec","repo":"apache/pulsar","slug":"either-s3managedledgeroffloadregion-or-s3managedle-d6dcbe","errorCode":null,"errorMessage":"Either s3ManagedLedgerOffloadRegion or s3ManagedLedgerOffloadServiceEndpoint must be set if s3 offload enabled","messagePattern":"Either s3ManagedLedgerOffloadRegion or s3ManagedLedgerOffloadServiceEndpoint must be set if s3 offload enabled","errorType":"validation","errorClass":"ParameterException","httpStatus":null,"severity":"error","filePath":"pulsar-client-tools/src/main/java/org/apache/pulsar/admin/cli/CmdTopics.java","lineNumber":2117,"sourceCode":"\n        public boolean isS3Driver(String driver) {\n            if (StringUtils.isEmpty(driver)) {\n                return false;\n            }\n            return driver.equalsIgnoreCase(driverNames.get(0)) || driver.equalsIgnoreCase(driverNames.get(1));\n        }\n\n        @Override\n        void run() throws PulsarAdminException {\n            String persistentTopic = validatePersistentTopic(topicName);\n\n            if (!driverSupported(driver)) {\n                throw new ParameterException(\n                  \"The driver \" + driver + \" is not supported, \"\n                    + \"(Possible values: \" + String.join(\",\", driverNames) + \").\");\n            }\n            if (isS3Driver(driver) && Strings.isNullOrEmpty(region) && Strings.isNullOrEmpty(endpoint)) {\n                throw new ParameterException(\n                  \"Either s3ManagedLedgerOffloadRegion or s3ManagedLedgerOffloadServiceEndpoint must be set\"\n                    + \" if s3 offload enabled\");\n            }\n\n            OffloadedReadPriority offloadedReadPriority = OffloadPoliciesImpl.DEFAULT_OFFLOADED_READ_PRIORITY;\n            if (this.offloadReadPriorityStr != null) {\n                try {\n                    offloadedReadPriority = OffloadedReadPriority.fromString(this.offloadReadPriorityStr);\n                } catch (Exception e) {\n                    throw new ParameterException(\"--offloadedReadPriority parameter must be one of \"\n                            + Arrays.stream(OffloadedReadPriority.values())\n                                    .map(OffloadedReadPriority::toString)\n                                    .collect(Collectors.joining(\",\"))\n                            + \" but got: \" + this.offloadReadPriorityStr, e);\n                }\n            }\n\n            OffloadPolicies offloadPolicies = OffloadPoliciesImpl.create(driver, region, bucket, endpoint,","sourceCodeStart":2099,"sourceCodeEnd":2135,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-client-tools/src/main/java/org/apache/pulsar/admin/cli/CmdTopics.java#L2099-L2135","documentation":"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.","triggerScenarios":"Running `pulsar-admin topics set-offload-policies --driver aws-s3` (or another S3 driver) without passing --s3ManagedLedgerOffloadRegion and without --s3ManagedLedgerOffloadServiceEndpoint.","commonSituations":"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.","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."],"exampleFix":"// before\nbin/pulsar-admin topics set-offload-policies my-topic --driver aws-s3 --bucket my-bucket\n// after\nbin/pulsar-admin topics set-offload-policies my-topic --driver aws-s3 --bucket my-bucket --s3ManagedLedgerOffloadRegion us-east-1","handlingStrategy":"validation","validationCode":"// require region or endpoint for S3-family drivers\ncase \"$DRIVER\" in\n  aws-s3|s3)\n    if [ -z \"$REGION\" ] && [ -z \"$ENDPOINT\" ]; then\n      echo \"s3ManagedLedgerOffloadRegion or s3ManagedLedgerOffloadServiceEndpoint required\"; exit 1;\n    fi ;;\nesac","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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."],"tags":["cli","offload","s3","argument-validation"],"backgroundTag":"missing-required-config","analyzedSha":"820761864ed8e2a7d2e52dd9763ad2ae117c1395","analyzedAt":"2026-09-06T00:14:20.138Z","contentChangedAt":"2026-09-06T00:14:20.138Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}