{"record":{"id":"ab9852948001cceb","repo":"apache/pulsar","slug":"either-s3managedledgeroffloadregion-or-s3managedle","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/CmdNamespaces.java","lineNumber":2351,"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 namespace = validateNamespace(namespaceName);\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\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":2333,"sourceCodeEnd":2369,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-client-tools/src/main/java/org/apache/pulsar/admin/cli/CmdNamespaces.java#L2333-L2369","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Pass --region with the bucket's AWS region, e.g. --region us-west-2","Or pass --service-endpoint pointing at the S3-compatible endpoint, e.g. --service-endpoint http://s3.amazonaws.com or a MinIO endpoint","For MinIO/other S3-compatible storage, supply --service-endpoint; for plain AWS S3, supplying --region is usually enough","Switch to a driver that does not require region/endpoint if storage is not S3-compatible (e.g. azureblob, gcs)"],"exampleFix":"// before\npulsar-admin namespaces set-offload-policies --driver s3 --bucket my-bucket\n// after\npulsar-admin namespaces set-offload-policies --driver s3 --bucket my-bucket --region us-west-2","handlingStrategy":"validation","validationCode":"if (isS3Driver(driver) && (region == null || region.isEmpty()) && (endpoint == null || endpoint.isEmpty())) {\n    throw new IllegalArgumentException(\"Set --region or --service-endpoint for S3 offload\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    admin.namespaces().setOffloadPolicies(ns, policies);\n} catch (org.apache.pulsar.client.admin.PulsarAdminException e) {\n    // handle missing S3 region/endpoint config\n}","preventionTips":["Always pass --region for AWS S3 offloads","Always pass --service-endpoint for MinIO or other S3-compatible endpoints","Keep offload settings consistent between broker.conf and CLI invocations"],"tags":["cli","s3","configuration","validation"],"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"}