{"record":{"id":"234485316bc25d04","repo":"apache/pulsar","slug":"offloadedreadpriority-parameter-must-be-one-of-234485","errorCode":null,"errorMessage":"--offloadedReadPriority parameter must be one of ${validValues} but got: ${value}","messagePattern":"--offloadedReadPriority parameter must be one of (.+?) but got: (.+?)","errorType":"validation","errorClass":"ParameterException","httpStatus":null,"severity":"error","filePath":"pulsar-client-tools/src/main/java/org/apache/pulsar/admin/cli/CmdTopics.java","lineNumber":2127,"sourceCode":"            String persistentTopic = validatePersistentTopic(topicName);\n\n            if (!driverSupported(driver)) {\n                throw new ParameterException(\n                  \"The driver \" + driver + \" is not supported, \"\n                    + \"(Possible values: \" + String.join(\",\", driverNames) + \").\");\n            }\n            if (isS3Driver(driver) && Strings.isNullOrEmpty(region) && Strings.isNullOrEmpty(endpoint)) {\n                throw new ParameterException(\n                  \"Either s3ManagedLedgerOffloadRegion or s3ManagedLedgerOffloadServiceEndpoint must be set\"\n                    + \" if s3 offload enabled\");\n            }\n\n            OffloadedReadPriority offloadedReadPriority = OffloadPoliciesImpl.DEFAULT_OFFLOADED_READ_PRIORITY;\n            if (this.offloadReadPriorityStr != null) {\n                try {\n                    offloadedReadPriority = OffloadedReadPriority.fromString(this.offloadReadPriorityStr);\n                } catch (Exception e) {\n                    throw new ParameterException(\"--offloadedReadPriority parameter must be one of \"\n                            + Arrays.stream(OffloadedReadPriority.values())\n                                    .map(OffloadedReadPriority::toString)\n                                    .collect(Collectors.joining(\",\"))\n                            + \" but got: \" + this.offloadReadPriorityStr, e);\n                }\n            }\n\n            OffloadPolicies offloadPolicies = OffloadPoliciesImpl.create(driver, region, bucket, endpoint,\n                    s3Role, s3RoleSessionName,\n                    awsId, awsSecret,\n                    maxBlockSizeInBytes, readBufferSizeInBytes, offloadAfterThresholdInBytes,\n                    offloadThresholdInSeconds, offloadAfterElapsedInMillis, offloadedReadPriority);\n\n            getTopics().setOffloadPolicies(persistentTopic, offloadPolicies);\n        }\n    }\n\n    @Command(description = \"Set the persistence policies for a topic\", hidden = true)","sourceCodeStart":2109,"sourceCodeEnd":2145,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-client-tools/src/main/java/org/apache/pulsar/admin/cli/CmdTopics.java#L2109-L2145","documentation":"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).","triggerScenarios":"Running `pulsar-admin topics set-offload-policies <topic> --offloadedReadPriority <value>` where <value> is misspelled, wrong-cased, or not one of the enum constants.","commonSituations":"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`).","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."],"exampleFix":"// before\nbin/pulsar-admin topics set-offload-policies my-topic --driver aws-s3 --bucket b --offloadedReadPriority broker-first\n// after\nbin/pulsar-admin topics set-offload-policies my-topic --driver aws-s3 --bucket b --offloadedReadPriority tiered-storage-first","handlingStrategy":"validation","validationCode":"// validate against allowed OffloadedReadPriority values\nVALID=\"tiered-storage-first,ledger-first,direct-empty\"\nif [ -n \"$PRIORITY\" ] && ! echo \",$VALID,\" | grep -q \",$PRIORITY,\"; then\n  echo \"invalid --offloadedReadPriority: $PRIORITY (possible: $VALID)\"; exit 1;\nfi","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Copy flag values exactly as lowercase hyphenated enum names.","Omit --offloadedReadPriority to accept the default.","Document the valid values next to your deployment scripts."],"tags":["cli","argument-validation","offload","enum"],"backgroundTag":"invalid-enum-value","analyzedSha":"820761864ed8e2a7d2e52dd9763ad2ae117c1395","analyzedAt":"2026-09-06T00:14:20.138Z","contentChangedAt":"2026-09-06T00:14:20.138Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}