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 offload command (set-offload-policies) validates the --driver value against the supported driver list before applying offload policies. If driverSupported(driver) returns false, it throws a ParameterException listing the allowed driver names. This prevents submitting an offload driver the broker cannot load.

Source

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

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

            OffloadedReadPriority offloadedReadPriority = OffloadPoliciesImpl.DEFAULT_OFFLOADED_READ_PRIORITY;
            if (this.offloadReadPriorityStr != null) {
                try {
                    offloadedReadPriority = OffloadedReadPriority.fromString(this.offloadReadPriorityStr);
                } catch (Exception e) {
                    throw new ParameterException("--offloadedReadPriority parameter must be one of "
                            + Arrays.stream(OffloadedReadPriority.values())
                                    .map(OffloadedReadPriority::toString)
                                    .collect(Collectors.joining(","))

View on GitHub (pinned to 820761864e)

Solutions

Use one of the driver names printed in the error message, e.g. `--driver aws-s3`.
Check supported names via the error's Possible values list or the OffloadedStoragePrefix docs for your Pulsar version.
If the driver genuinely should be supported, verify broker and CLI versions match and the offloader bundle is installed.

Example fix

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

Defensive patterns

Strategy: validation

Validate before calling

// validate driver against the supported set
SUPPORTED="aws-s3,s3,google-cloud-storage,azureblob,filesystem"
if ! echo ",$SUPPORTED," | grep -q ",$DRIVER,"; then
  echo "unsupported driver: $DRIVER (possible: $SUPPORTED)"; exit 1;
fi

Prevention

Keep a script-local whitelist of driver names matching your Pulsar version.
Use exact driver identifiers from the error's Possible values list.
Pin the Pulsar CLI version in CI so driver names don't drift.

When it happens

Trigger: Running `pulsar-admin topics set-offload-policies <topic> --driver <name>` where <name> is misspelled or not in the supported set (e.g. `s3` vs `aws-s3`, `filesystem`, `azureblob`, `google-cloud-storage`).

Common situations: Copying driver names from docs of a different Pulsar version; typos like `S3` (case sensitivity); using a driver bundled only on the broker but not registered in the CLI's supported list.

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

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