apache/pulsar · error · org.apache.pulsar.broker.admin.RestException

The offloadPolicies must be specified for namespace offload.

Error message

The offloadPolicies must be specified for namespace offload.

What it means

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.

Source

Thrown at pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/AdminResource.java:1050

        return String.format("Subscription %s not found for topic %s", subscription, topic);
    }

    protected List<String> filterSystemTopic(List<String> topics, boolean includeSystemTopic) {
        return topics.stream()
                .filter(topic -> includeSystemTopic ? true : !pulsar().getBrokerService().isSystemTopic(topic))
                .collect(Collectors.toList());
    }

    protected AuthorizationService getAuthorizationService() {
        return pulsar().getBrokerService().getAuthorizationService();
    }

    protected void validateOffloadPolicies(OffloadPoliciesImpl offloadPolicies) {
        if (offloadPolicies == null) {
            log.warn()
                    .attr("namespace", namespaceName)
                    .log("Failed to update offload configuration for namespace : offloadPolicies is null");
            throw new RestException(Status.PRECONDITION_FAILED,
                    "The offloadPolicies must be specified for namespace offload.");
        }
        if (!offloadPolicies.driverSupported()) {
            log.warn()
                    .attr("namespace", namespaceName)
                    .attr("value", OffloadPoliciesImpl.getSupportedDriverNames())
                    .log("Failed to update offload configuration for namespace: driver is not supported, support"
                            + " value");
            throw new RestException(Status.PRECONDITION_FAILED,
                    "The driver is not supported, support value: " + OffloadPoliciesImpl.getSupportedDriverNames());
        }
        if (!offloadPolicies.bucketValid()) {
            log.warn()
                    .attr("namespace", namespaceName)
                    .log("Failed to update offload configuration for namespace : bucket must be specified");
            throw new RestException(Status.PRECONDITION_FAILED,
                    "The bucket must be specified for namespace offload.");
        }

View on GitHub (pinned to 820761864e)

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.

Example fix

// before (412: null policy)
admin.namespaces().setOffloadPolicies(ns, null);
// after
OffloadPoliciesImpl policies = OffloadPoliciesImpl.builder()
    .setDriver("S3")
    .setBucket("my-bucket")
    .setRegion("us-east-1")
    .build();
admin.namespaces().setOffloadPolicies(ns, policies);

Defensive patterns

Strategy: validation

Validate before calling

// Java
if (policies == null
    || policies.getDriver() == null || policies.getDriver().isBlank()
    || policies.getBucket() == null || policies.getBucket().isBlank()) {
    throw new IllegalArgumentException("offloadPolicies with driver and bucket required");
}

Try / catch

try {
    admin.namespaces().setOffloadPolicies(ns, policies);
} catch (PulsarAdminException.PreconditionFailedException e) {
    if (e.getMessage().contains("offloadPolicies must be specified")) {
        // rebuild a complete OffloadPoliciesImpl and retry once
    }
}

Prevention

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.

When it happens

Trigger: Calling namespace admin APIs that update offload policies — setOffloadPolicies / updateProperties-style policy updates that include offload config — with offloadPolicies == null in the request body.

Common situations: 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.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

AI-assisted analysis of apache/pulsar@820761864e (2026-09-06). Data as JSON: /api/errors/14fd1beecaa6e2d0. Report an issue: GitHub.