apache/pulsar · error · ParameterException

The driver ${driver} is not supported, (Possible values: ${d

Error message

The driver ${driver} is not supported, (Possible values: ${driverNames}).

What it means

The set-offload-policies command checks the chosen offload driver against the list of drivers supported by this CLI build (driverSupported). Unsupported names (including typos or drivers from a different Pulsar version/distribution) are rejected with this ParameterException listing the possible values.

Source

Thrown at pulsar-client-tools/src/main/java/org/apache/pulsar/admin/cli/CmdTopicPolicies.java:1865

        public final List<String> driverNames = OffloadPoliciesImpl.DRIVER_NAMES;

        public boolean driverSupported(String driver) {
            return driverNames.stream().anyMatch(d -> d.equalsIgnoreCase(driver));
        }

        public boolean isS3Driver(String driver) {
            if (StringUtils.isEmpty(driver)) {
                return false;
            }
            return driver.equalsIgnoreCase(driverNames.get(0)) || driver.equalsIgnoreCase(driverNames.get(1));
        }

        @Override
        void run() throws PulsarAdminException {
            String persistentTopic = validatePersistentTopic(topicName);

            if (!driverSupported(driver)) {
                throw new ParameterException("The driver " + driver + " is not supported, "
                        + "(Possible values: " + String.join(",", driverNames) + ").");
            }

            if (isS3Driver(driver) && Strings.isNullOrEmpty(region) && Strings.isNullOrEmpty(endpoint)) {
                throw new ParameterException(
                        "Either s3ManagedLedgerOffloadRegion or s3ManagedLedgerOffloadServiceEndpoint must be set"
                                + " if s3 offload enabled");
            }
            positiveCheck("maxBlockSizeInBytes", maxBlockSizeInBytes);
            maxValueCheck("maxBlockSizeInBytes", maxBlockSizeInBytes, Integer.MAX_VALUE);
            positiveCheck("readBufferSizeInBytes", readBufferSizeInBytes);
            maxValueCheck("readBufferSizeInBytes", readBufferSizeInBytes, Integer.MAX_VALUE);

            OffloadedReadPriority offloadedReadPriority = OffloadPoliciesImpl.DEFAULT_OFFLOADED_READ_PRIORITY;

            if (this.offloadReadPriorityStr != null) {
                try {
                    offloadedReadPriority = OffloadedReadPriority.fromString(this.offloadReadPriorityStr);

View on GitHub (pinned to 820761864e)

Solutions

1. Use one of the driver names printed in the error (e.g. s3, aws-s3, gcs, filesystem depending on your build)
2. Check your Pulsar version's documentation for the exact --driver strings and available provider modules
3. If the driver exists upstream but not in your build, use a distribution that bundles the corresponding offload provider

Example fix

// before
pulsar-admin topics set-offload-policies my-topic --driver s3ManagedLedgerOffloadDriver --bucket my-bucket
// after
pulsar-admin topics set-offload-policies my-topic --driver s3 --bucket my-bucket --region us-east-1

if (!Arrays.asList("s3","aws-s3","gcs","azureblob","filesystem","aliyun-oss").contains(driver)) {
    throw new IllegalArgumentException("unsupported offload driver: " + driver);
} // verify against your build's supported list printed in the error

When it happens

Trigger: Running set-offload-policies with --driver set to a misspelled name, an enterprise-only/distribution-specific driver (e.g. azureblob, aliyun-oss on a build without that provider), or a driver renamed between Pulsar versions (e.g. s3 vs aws-s3).

Common situations: Following docs for a different Pulsar version where the driver string changed; using cloud-specific driver names copied from vendor guides; builds excluding optional offload provider modules so a nominally valid driver is absent.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• --offloadedReadPriority parameter must be one of ${validValu
• Need to provide a persistent topic name
• Need to provide a non-persistent topic name
• Invalid message id (must be in format: ledgerId:entryId) val
• unable to parse namespaces parameter list:

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