{"record":{"id":"6cf6eabe423b343b","repo":"apache/pulsar","slug":"invalid-retention-policy-type-s-valid-options","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":"error","filePath":"pulsar-client-tools/src/main/java/org/apache/pulsar/admin/cli/CmdNamespaces.java","lineNumber":1308,"sourceCode":"                required = true)\n        private String policyStr;\n\n        @Option(names = {\"-t\", \"--type\"}, description = \"Backlog quota type to set. Valid options are: \"\n                + \"destination_storage (default) and message_age. \"\n                + \"destination_storage limits backlog by size. \"\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 namespace = validateNamespace(namespaceName);\n\n            BacklogQuota.Builder builder = BacklogQuota.builder().retentionPolicy(policy);\n            if (backlogQuotaType == BacklogQuota.BacklogQuotaType.destination_storage) {\n                // set quota by storage size\n                if (limit == null) {\n                    throw new ParameterException(\"Quota type of 'destination_storage' needs a size limit\");\n                }","sourceCodeStart":1290,"sourceCodeEnd":1326,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-client-tools/src/main/java/org/apache/pulsar/admin/cli/CmdNamespaces.java#L1290-L1326","documentation":"When setting a namespace backlog quota, the --retention-policy value is parsed with BacklogQuota.RetentionPolicy.valueOf(). Any string other than the enum constants (producer_exception, producer_request_hold, consumer_backlog_eviction, target_storage, etc. depending on version) fails parsing and the CLI throws this ParameterException listing the valid values.","triggerScenarios":"Running `pulsar-admin namespaces set-backlog-quota <ns> --retention-policy <bad-string> ...` where policyStr is not an exact RetentionPolicy constant (case-sensitive valueOf).","commonSituations":"Typos or wrong case (e.g. 'Producer_Exception'); inventing values like 'reject' or 'drop'; copying values from a different Pulsar version where the enum changed.","solutions":["Use one of the values printed in the error message from Arrays.toString(RetentionPolicy.values())","Fix case/typos — valueOf is case-sensitive (e.g. use producer_exception)","Check the enum values for your exact Pulsar version"],"exampleFix":"// before\npulsar-admin namespaces set-backlog-quota my-tenant/my-ns --retention-policy Reject --limit-size 10G\n// after\npulsar-admin namespaces set-backlog-quota my-tenant/my-ns --retention-policy producer_exception --limit-size 10G","handlingStrategy":"validation","validationCode":"// pre-check in Java before invoking\nboolean valid = Arrays.stream(BacklogQuota.RetentionPolicy.values())\n        .anyMatch(v -> v.name().equals(policyStr));","typeGuard":"function isValidRetentionPolicy(s) { return ['producer_exception','producer_request_hold','consumer_backlog_eviction','target_storage'].includes(s); }","tryCatchPattern":"try {\n    admin.namespaces().setBacklogQuota(ns, quota, type);\n} catch (IllegalArgumentException e) {\n    // print BacklogQuota.RetentionPolicy.values() and correct the argument\n}","preventionTips":["Copy enum values from the error message verbatim","Remember valueOf is case-sensitive","Pin scripts to a Pulsar version and verify enum values on upgrade"],"tags":["cli","enum-parsing","backlog-quota","pulsar-admin"],"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"}