{"record":{"id":"231ea110d2e2842b","repo":"apache/pulsar","slug":"the-bucket-must-be-specified-for-namespace-offload","errorCode":null,"errorMessage":"The bucket must be specified for namespace offload.","messagePattern":"The bucket must be specified for namespace offload\\.","errorType":"http","errorClass":"RestException","httpStatus":412,"severity":"error","filePath":"pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/AdminResource.java","lineNumber":1066,"sourceCode":"                    .attr(\"namespace\", namespaceName)\n                    .log(\"Failed to update offload configuration for namespace : offloadPolicies is null\");\n            throw new RestException(Status.PRECONDITION_FAILED,\n                    \"The offloadPolicies must be specified for namespace offload.\");\n        }\n        if (!offloadPolicies.driverSupported()) {\n            log.warn()\n                    .attr(\"namespace\", namespaceName)\n                    .attr(\"value\", OffloadPoliciesImpl.getSupportedDriverNames())\n                    .log(\"Failed to update offload configuration for namespace: driver is not supported, support\"\n                            + \" value\");\n            throw new RestException(Status.PRECONDITION_FAILED,\n                    \"The driver is not supported, support value: \" + OffloadPoliciesImpl.getSupportedDriverNames());\n        }\n        if (!offloadPolicies.bucketValid()) {\n            log.warn()\n                    .attr(\"namespace\", namespaceName)\n                    .log(\"Failed to update offload configuration for namespace : bucket must be specified\");\n            throw new RestException(Status.PRECONDITION_FAILED,\n                    \"The bucket must be specified for namespace offload.\");\n        }\n    }\n\n    protected CompletableFuture<Void> internalCheckTopicExists(TopicName topicName) {\n        return pulsar().getNamespaceService().checkTopicExistsAsync(topicName)\n                .thenAccept(info -> {\n                    boolean exists = info.isExists();\n                    info.recycle();\n                    if (!exists) {\n                        throw new RestException(Status.NOT_FOUND, getTopicNotFoundErrorMessage(topicName.toString()));\n                    }\n                });\n    }\n}\n","sourceCodeStart":1048,"sourceCodeEnd":1082,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/AdminResource.java#L1048-L1082","documentation":"Namespace offload policies must include a valid bucket (target storage container); when bucketValid() returns false — bucket null/blank, or invalid for the chosen driver — the update is rejected with HTTP 412 PRECONDITION_FAILED. The bucket is where ledgers are offloaded, so it is mandatory.","triggerScenarios":"Calling the namespace offload policy update API (setOffloadPolicies) with OffloadPolicies missing the bucket field, or with a bucket value that fails the driver-specific validity check (e.g. empty string, or for filesystem driver an absent file-system base path variant of 'bucket').","commonSituations":"1) Config template/env var for the bucket name is empty at deploy time. 2) User configured region/credentials/endpoint but forgot the bucket. 3) For filesystem offloader, the 'bucket' is expected to be an absolute path and a relative path fails validity.","solutions":["Set the bucket field in OffloadPolicies to an existing storage bucket you have write access to, then retry the update.","For filesystem offload, set bucket to an absolute local/POSIX path (the filesystem driver uses it as the base directory).","Fix the deployment template so the bucket env/config variable is actually populated before calling the admin API.","Verify with the provider (aws s3 ls / gsutil ls) that the bucket exists and the broker's credentials can access it; some drivers' bucketValid also checks path form."],"exampleFix":"// before (412: no bucket)\nOffloadPoliciesImpl p = OffloadPoliciesImpl.builder().setDriver(\"aws-s3\").setRegion(\"us-east-1\").build();\n// after\nOffloadPoliciesImpl p = OffloadPoliciesImpl.builder()\n    .setDriver(\"aws-s3\")\n    .setBucket(\"pulsar-offload-prod\")\n    .setRegion(\"us-east-1\")\n    .build();","handlingStrategy":"validation","validationCode":"// Java\nString bucket = policies.getBucket();\nif (bucket == null || bucket.isBlank()\n    || (\"filesystem\".equals(policies.getDriver()) && !bucket.startsWith(\"/\"))) {\n    throw new IllegalArgumentException(\"offload bucket must be set (absolute path for filesystem driver)\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    admin.namespaces().setOffloadPolicies(ns, policies);\n} catch (PulsarAdminException.PreconditionFailedException e) {\n    if (e.getMessage().contains(\"bucket must be specified\")) {\n        // set policies.setBucket(...) and retry once\n    }\n}","preventionTips":["Always set bucket together with driver/region when building offload policies.","For filesystem offload, use an absolute path as the bucket value.","Assert bucket config variables are non-empty in deployment pipelines before invoking the admin API.","Confirm bucket existence and broker credentials with the storage provider before configuring offload."],"tags":["pulsar","broker","precondition-failed","offload","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"}