{"record":{"id":"d79db4d95b525fc9","repo":"apache/pulsar","slug":"invalid-retention-policy-type-s-valid-options-d79db4","errorCode":null,"errorMessage":"Invalid retention policy type '%s'. Valid options are: %s","messagePattern":"Invalid retention policy type '(.+?)'\\. Valid options are: (.+?)","errorType":"validation","errorClass":"ParameterException","httpStatus":null,"severity":"warning","filePath":"pulsar-client-tools/src/main/java/org/apache/pulsar/admin/cli/CmdTopics.java","lineNumber":1535,"sourceCode":"                        + \"[producer_request_hold, producer_exception, consumer_backlog_eviction]\", required = true)\n        private String policyStr;\n\n        @Option(names = {\"-t\", \"--type\"}, description = \"Backlog quota type to set. Valid options are: \"\n                + \"destination_storage and message_age. \"\n                + \"destination_storage limits backlog by size (in bytes). \"\n                + \"message_age limits backlog by time, that is, message timestamp (broker or publish timestamp). \"\n                + \"You can set size or time to control the backlog, or combine them together to control the backlog. \")\n        private String backlogQuotaTypeStr = BacklogQuota.BacklogQuotaType.destination_storage.name();\n\n        @Override\n        void run() throws PulsarAdminException {\n            BacklogQuota.RetentionPolicy policy;\n            BacklogQuota.BacklogQuotaType backlogQuotaType;\n\n            try {\n                policy = BacklogQuota.RetentionPolicy.valueOf(policyStr);\n            } catch (IllegalArgumentException e) {\n                throw new ParameterException(String.format(\"Invalid retention policy type '%s'. Valid options are: %s\",\n                        policyStr, Arrays.toString(BacklogQuota.RetentionPolicy.values())));\n            }\n\n            try {\n                backlogQuotaType = BacklogQuota.BacklogQuotaType.valueOf(backlogQuotaTypeStr);\n            } catch (IllegalArgumentException e) {\n                throw new ParameterException(String.format(\"Invalid backlog quota type '%s'. Valid options are: %s\",\n                        backlogQuotaTypeStr, Arrays.toString(BacklogQuota.BacklogQuotaType.values())));\n            }\n\n            String persistentTopic = validatePersistentTopic(topicName);\n            getTopics().setBacklogQuota(persistentTopic,\n                    BacklogQuota.builder().limitSize(limit)\n                            .limitTime(limitTimeInSec.intValue())\n                            .retentionPolicy(policy)\n                            .build(),\n                    backlogQuotaType);\n        }","sourceCodeStart":1517,"sourceCodeEnd":1553,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-client-tools/src/main/java/org/apache/pulsar/admin/cli/CmdTopics.java#L1517-L1553","documentation":"When setting a topic backlog quota, the --policy value must be a valid BacklogQuota.RetentionPolicy enum name. An unrecognized string throws IllegalArgumentException, which the CLI converts to ParameterException listing valid options.","triggerScenarios":"Running `pulsar-admin topics set-backlog-quota <topic> --policy <bad-value> ...` where policyStr is not exactly one of the RetentionPolicy values (producer_exception, producer_request_hold, consumer_backlog_eviction).","commonSituations":"Typos or wrong casing (valueOf is case-sensitive); using names from other contexts; older/newer enum names; quoting issues in shell scripts.","solutions":["Use an exact valid policy name: producer_exception, producer_request_hold, or consumer_backlog_eviction","Check the valid options printed in the error message","Note names are case-sensitive — no uppercase or hyphenated variants"],"exampleFix":"// before\npulsar-admin topics set-backlog-quota my-topic --policy evict ... \n// after\npulsar-admin topics set-backlog-quota my-topic --policy consumer_backlog_eviction ...","handlingStrategy":"validation","validationCode":"Set<String> valid = Set.of(\"producer_exception\", \"producer_request_hold\", \"consumer_backlog_eviction\");\nif (!valid.contains(policyStr)) {\n    throw new IllegalArgumentException(\"policy must be one of \" + valid);\n}","typeGuard":null,"tryCatchPattern":"try {\n    BacklogQuota.RetentionPolicy.valueOf(policyStr);\n} catch (IllegalArgumentException e) {\n    log.error(\"Invalid retention policy '{}'; valid: {}\", policyStr,\n        Arrays.toString(BacklogQuota.RetentionPolicy.values()));\n}","preventionTips":["Use exact lowercase enum names: producer_exception, producer_request_hold, consumer_backlog_eviction","Remember valueOf is case-sensitive","Copy values from the error message's 'Valid options' list"],"tags":["cli","parameter-validation","backlog-quota","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-14T05:17:10.506Z"}