{"record":{"id":"db32300152f133f9","repo":"apache/pulsar","slug":"either-s3managedledgeroffloadregion-or-s3managedle-db3230","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/CmdTopicPolicies.java","lineNumber":1870,"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(\"The driver \" + driver + \" is not supported, \"\n                        + \"(Possible values: \" + String.join(\",\", driverNames) + \").\");\n            }\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            positiveCheck(\"maxBlockSizeInBytes\", maxBlockSizeInBytes);\n            maxValueCheck(\"maxBlockSizeInBytes\", maxBlockSizeInBytes, Integer.MAX_VALUE);\n            positiveCheck(\"readBufferSizeInBytes\", readBufferSizeInBytes);\n            maxValueCheck(\"readBufferSizeInBytes\", readBufferSizeInBytes, Integer.MAX_VALUE);\n\n            OffloadedReadPriority offloadedReadPriority = OffloadPoliciesImpl.DEFAULT_OFFLOADED_READ_PRIORITY;\n\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(\",\"))","sourceCodeStart":1852,"sourceCodeEnd":1888,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-client-tools/src/main/java/org/apache/pulsar/admin/cli/CmdTopicPolicies.java#L1852-L1888","documentation":"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.","triggerScenarios":"Running set-offload-policies with --driver s3 (or another isS3Driver match) while omitting both --region and --service-endpoint flags.","commonSituations":"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.","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"],"exampleFix":"// before\npulsar-admin topics set-offload-policies my-topic --driver s3 --bucket my-bucket\n// after\npulsar-admin topics set-offload-policies my-topic --driver s3 --bucket my-bucket --region us-east-1","handlingStrategy":"validation","validationCode":"if (isS3Driver(driver) && isBlank(region) && isBlank(serviceEndpoint)) {\n    throw new IllegalArgumentException(\"S3 offload requires --region or --service-endpoint\");\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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"],"tags":["cli","pulsar-admin","offload","s3","missing-argument"],"backgroundTag":"missing-required-argument","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"}