apache/pulsar · error · IllegalArgumentException

--offloadedReadPriority parameter must be one of ${allowed}

Error message

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

What it means

OffloadedReadPriority.fromString parses the --offloadedReadPriority value ('ledgers first' ordering variants like 'ledgerfirst'/'bookkeeperfirst') and throws IllegalArgumentException listing all allowed values when the input doesn't match any. It's a strict CLI/config value parser for tiered-storage read priority.

Source

Thrown at pulsar-client-admin-api/src/main/java/org/apache/pulsar/common/policies/data/OffloadedReadPriority.java:62

    }

    public boolean equalsName(String otherName) {
        return value.equals(otherName);
    }

    @Override
    public String toString() {
        return value;
    }

    public static OffloadedReadPriority fromString(String str) {
        for (OffloadedReadPriority value : OffloadedReadPriority.values()) {
            if (value.value.equals(str)) {
                return value;
            }
        }

        throw new IllegalArgumentException("--offloadedReadPriority parameter must be one of "
                + Arrays.stream(OffloadedReadPriority.values())
                .map(OffloadedReadPriority::toString)
                .collect(Collectors.joining(","))
                + " but got: " + str);
    }

    public String getValue() {
        return value;
    }
}

View on GitHub (pinned to 820761864e)

Solutions

1. Use exactly one of the allowed values listed in the error message (e.g. ledgerfirst, bookkeeperfirst)
2. Check case and spacing: the comparison is exact (value.value.equals(str))
3. Copy the allowed list from the OffloadedReadPriority enum in the version you are deploying

Example fix

// before
--offloadedReadPriority LedgerFirst
// after
--offloadedReadPriority ledgerfirst

boolean isValidOffloadedReadPriority(String s) {
    return Arrays.stream(OffloadedReadPriority.values())
        .anyMatch(p -> p.toString().equals(s));
}

try {
    OffloadedReadPriority p = OffloadedReadPriority.fromString(value);
} catch (IllegalArgumentException e) {
    logger.error("Bad --offloadedReadPriority '{}': use one of ledgerfirst,bookkeeperfirst", value);
}

When it happens

Trigger: Calling OffloadedReadPriority.fromString(str) with a misspelled, mis-cased, or empty string, e.g. 'LedgerFirst', 'ledger_first', or 'bookkeeper-first' instead of the exact allowed tokens.

Common situations: Typo in broker.conf or CLI flag --offloadedReadPriority, copying values from older docs where naming differed, environment-specific config templating producing empty 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

• --offloadedReadPriority parameter must be one of %s but got:
• Invalid value '' for enum
• Malformed configuration file
• Need to specify a configuration file for broker
• No configuration file for Bookie

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