apache/pulsar · error · RestException

The bucket must be specified for namespace offload.

Error message

The bucket must be specified for namespace offload.

What it means

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.

Source

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

                    .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.");
        }
    }

    protected CompletableFuture<Void> internalCheckTopicExists(TopicName topicName) {
        return pulsar().getNamespaceService().checkTopicExistsAsync(topicName)
                .thenAccept(info -> {
                    boolean exists = info.isExists();
                    info.recycle();
                    if (!exists) {
                        throw new RestException(Status.NOT_FOUND, getTopicNotFoundErrorMessage(topicName.toString()));
                    }
                });
    }
}

View on GitHub (pinned to 820761864e)

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.

Example fix

// before (412: no bucket)
OffloadPoliciesImpl p = OffloadPoliciesImpl.builder().setDriver("aws-s3").setRegion("us-east-1").build();
// after
OffloadPoliciesImpl p = OffloadPoliciesImpl.builder()
    .setDriver("aws-s3")
    .setBucket("pulsar-offload-prod")
    .setRegion("us-east-1")
    .build();

Defensive patterns

Strategy: validation

Validate before calling

// Java
String bucket = policies.getBucket();
if (bucket == null || bucket.isBlank()
    || ("filesystem".equals(policies.getDriver()) && !bucket.startsWith("/"))) {
    throw new IllegalArgumentException("offload bucket must be set (absolute path for filesystem driver)");
}

Try / catch

try {
    admin.namespaces().setOffloadPolicies(ns, policies);
} catch (PulsarAdminException.PreconditionFailedException e) {
    if (e.getMessage().contains("bucket must be specified")) {
        // set policies.setBucket(...) and retry once
    }
}

Prevention

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.

When it happens

Trigger: 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').

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

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/231ea110d2e2842b. Report an issue: GitHub.