apache/pulsar · error · ParameterException

--offloadedReadPriority parameter must be one of %s but got:

Error message

--offloadedReadPriority parameter must be one of %s but got: %s

What it means

The --offloadedReadPriority option for set-offload-policies only accepts the enumerated values of OffloadedReadPriority (currently 'first' meaning read from offloaded storage first, or 'last'). Any other string fails OffloadedReadPriority.fromString and is wrapped in a ParameterException listing the valid values.

Source

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

            String namespace = validateNamespace(namespaceName);

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

            getAdmin().namespaces().setOffloadPolicies(namespace, offloadPolicies);
        }
    }

    @Command(description = "Remove the offload policies for a namespace")

View on GitHub (pinned to 820761864e)

Solutions

Use one of the exact values printed in the message, e.g. --offloadedReadPriority first or --offloadedReadPriority last
Check the OffloadedReadPriority enum in your Pulsar version for the exact accepted strings
Omit --offloadedReadPriority entirely to use the default read priority

Example fix

// before
pulsar-admin namespaces set-offload-policies --driver s3 --bucket b --offloadedReadPriority reader-first
// after
pulsar-admin namespaces set-offload-policies --driver s3 --bucket b --offloadedReadPriority first

Defensive patterns

Strategy: validation

Validate before calling

Set<String> valid = Set.of("first", "last");
if (offloadReadPriority != null && !valid.contains(offloadReadPriority)) {
    throw new IllegalArgumentException("--offloadedReadPriority must be one of " + valid);
}

Try / catch

try {
    OffloadedReadPriority p = OffloadedReadPriority.fromString(value);
} catch (IllegalArgumentException e) {
    // fall back to default read priority
}

Prevention

Copy enum values exactly, lowercase, from the error message
Check the OffloadedReadPriority enum for your Pulsar version
Prefer omitting the flag to use the default

When it happens

Trigger: Running `pulsar-admin namespaces set-offload-policies --offloadedReadPriority <value>` where <value> is not exactly one of the enum constants, e.g. misspellings like 'First', 'reader-first', or 'tiered'.

Common situations: Typo or casing mistake in the enum name; copying option values from documentation of a different Pulsar version where the enum had different members; shell completion inserting a wrong value.

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