apache/pulsar · error · ParameterException

--offloadedReadPriority parameter must be one of ${validValu

Error message

--offloadedReadPriority parameter must be one of ${validValues} but got: ${value}

What it means

The --offloadedReadPriority option of set-offload-policies is parsed via OffloadedReadPriority.fromString. Any value outside the enum's valid set causes an exception that is rethrown as a ParameterException listing the allowed values (e.g. tiered-storage-first, ledger-first, direct-empty).

Source

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

            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(","))
                            + " but got: " + this.offloadReadPriorityStr, e);
                }
            }

            OffloadPolicies offloadPolicies = OffloadPoliciesImpl.create(driver, region, bucket, endpoint,
                    s3Role, s3RoleSessionName,
                    awsId, awsSecret,
                    maxBlockSizeInBytes, readBufferSizeInBytes, offloadAfterThresholdInBytes,
                    offloadThresholdInSeconds, offloadAfterElapsedInMillis, offloadedReadPriority);

            getTopics().setOffloadPolicies(persistentTopic, offloadPolicies);
        }
    }

    @Command(description = "Set the persistence policies for a topic", hidden = true)

View on GitHub (pinned to 820761864e)

Solutions

Use one of the valid values listed in the error message (e.g. --offloadedReadPriority tiered-storage-first).
Omit the flag entirely to accept OffloadPoliciesImpl.DEFAULT_OFFLOADED_READ_PRIORITY.
Match the exact lowercase spelling and hyphenation shown in the message.

Example fix

// before
bin/pulsar-admin topics set-offload-policies my-topic --driver aws-s3 --bucket b --offloadedReadPriority broker-first
// after
bin/pulsar-admin topics set-offload-policies my-topic --driver aws-s3 --bucket b --offloadedReadPriority tiered-storage-first

Defensive patterns

Strategy: validation

Validate before calling

// validate against allowed OffloadedReadPriority values
VALID="tiered-storage-first,ledger-first,direct-empty"
if [ -n "$PRIORITY" ] && ! echo ",$VALID," | grep -q ",$PRIORITY,"; then
  echo "invalid --offloadedReadPriority: $PRIORITY (possible: $VALID)"; exit 1;
fi

Prevention

Copy flag values exactly as lowercase hyphenated enum names.
Omit --offloadedReadPriority to accept the default.
Document the valid values next to your deployment scripts.

When it happens

Trigger: Running `pulsar-admin topics set-offload-policies <topic> --offloadedReadPriority <value>` where <value> is misspelled, wrong-cased, or not one of the enum constants.

Common situations: Copy-pasting the flag from a blog post predating the option's final naming; using broker-side values like `broker` instead of the CLI enum values; case sensitivity (`TIERED-STORAGE-FIRST` vs `tiered-storage-first`).

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/234485316bc25d04. Report an issue: GitHub.