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 value is resolved via OffloadedReadPriority.fromString(); any string outside the known set (ledger, ledgers, tiered-storage) throws, and the CLI wraps the failure in a ParameterException enumerating the valid values and echoing the bad input.

Source

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

            }

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

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

            getTopicPolicies(isGlobal).setOffloadPolicies(persistentTopic, offloadPolicies);
        }
    }

View on GitHub (pinned to 820761864e)

Solutions

Use one of the values listed in the error message, e.g. 'ledger' or 'tiered-storage'
Verify against the OffloadedReadPriority enum in your Pulsar version
Omit the flag entirely to use the default priority

Example fix

// before
pulsar-admin topics set-offload-policies my-topic --driver s3 --region us-east-1 --offloadedReadPriority leadger
// after
pulsar-admin topics set-offload-policies my-topic --driver s3 --region us-east-1 --offloadedReadPriority ledger

Defensive patterns

Strategy: validation

Validate before calling

final Set<String> VALID = Arrays.stream(OffloadedReadPriority.values()).map(Enum::toString).collect(Collectors.toSet());
if (priority != null && !VALID.contains(priority)) throw new IllegalArgumentException("offloadedReadPriority must be one of " + VALID);

Prevention

Use exact enum strings like 'ledger' or 'tiered-storage'
Omit the flag to use the default
Match CLI version to docs version when scripting

When it happens

Trigger: Running set-offload-policies with --offloadedReadPriority set to an unknown string, wrong casing, or a value introduced in a newer Pulsar version than the CLI in use.

Common situations: Typo'd priority names in automation scripts; docs for newer Pulsar versions mentioning priorities the local CLI doesn't know; confusion with broker.conf property naming (offloadedReadPriority) versus the exact enum strings.

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/0f8aa075c0e48d6a. Report an issue: GitHub.