{"record":{"id":"14fd1beecaa6e2d0","repo":"apache/pulsar","slug":"the-offloadpolicies-must-be-specified-for-namespac","errorCode":null,"errorMessage":"The offloadPolicies must be specified for namespace offload.","messagePattern":"The offloadPolicies must be specified for namespace offload\\.","errorType":"http","errorClass":"org.apache.pulsar.broker.admin.RestException","httpStatus":412,"severity":"error","filePath":"pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/AdminResource.java","lineNumber":1050,"sourceCode":"        return String.format(\"Subscription %s not found for topic %s\", subscription, topic);\n    }\n\n    protected List<String> filterSystemTopic(List<String> topics, boolean includeSystemTopic) {\n        return topics.stream()\n                .filter(topic -> includeSystemTopic ? true : !pulsar().getBrokerService().isSystemTopic(topic))\n                .collect(Collectors.toList());\n    }\n\n    protected AuthorizationService getAuthorizationService() {\n        return pulsar().getBrokerService().getAuthorizationService();\n    }\n\n    protected void validateOffloadPolicies(OffloadPoliciesImpl offloadPolicies) {\n        if (offloadPolicies == null) {\n            log.warn()\n                    .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        }","sourceCodeStart":1032,"sourceCodeEnd":1068,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/AdminResource.java#L1032-L1068","documentation":"Updating namespace-level offload configuration requires an OffloadPolicies object; passing null is rejected with HTTP 412 PRECONDITION_FAILED. The broker cannot apply a null policy because offload requires driver/credential/bucket settings, and clearing offload config is not done by sending null through this validation path.","triggerScenarios":"Calling namespace admin APIs that update offload policies — setOffloadPolicies / updateProperties-style policy updates that include offload config — with offloadPolicies == null in the request body.","commonSituations":"1) Client deserialization yields null because the JSON body omitted the offloadPolicies field. 2) Automation sends an incomplete policies object where only some fields are set. 3) A user tries to 'unset' offload by posting null instead of using the dedicated remove/clear API.","solutions":["Send a fully populated OffloadPoliciesImpl with driver, bucket, region/endpoint and credentials set before calling the offload policy update API.","If the goal is to remove offload configuration, use the namespace removeOffloadPolicies (unset) admin API instead of posting null.","Check your client serialization: ensure the JSON key for offload policies is present and correctly nested so it isn't dropped to null.","Confirm the field names match your Pulsar version's OffloadPoliciesImpl schema (field names changed across versions), so Jackson doesn't silently null the object."],"exampleFix":"// before (412: null policy)\nadmin.namespaces().setOffloadPolicies(ns, null);\n// after\nOffloadPoliciesImpl policies = OffloadPoliciesImpl.builder()\n    .setDriver(\"S3\")\n    .setBucket(\"my-bucket\")\n    .setRegion(\"us-east-1\")\n    .build();\nadmin.namespaces().setOffloadPolicies(ns, policies);","handlingStrategy":"validation","validationCode":"// Java\nif (policies == null\n    || policies.getDriver() == null || policies.getDriver().isBlank()\n    || policies.getBucket() == null || policies.getBucket().isBlank()) {\n    throw new IllegalArgumentException(\"offloadPolicies with driver and bucket required\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    admin.namespaces().setOffloadPolicies(ns, policies);\n} catch (PulsarAdminException.PreconditionFailedException e) {\n    if (e.getMessage().contains(\"offloadPolicies must be specified\")) {\n        // rebuild a complete OffloadPoliciesImpl and retry once\n    }\n}","preventionTips":["Always build OffloadPolicies via its builder with driver+bucket set before calling the API.","When unsetting, use removeOffloadPolicies instead of null.","Verify JSON bodies serialize the offload policies field (watch for Jackson silently dropping it).","Add a pre-flight check in automation that the policies object is non-null and complete."],"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-14T00:17:10.932Z"}