{"record":{"id":"434e1dad1a53c2c8","repo":"apache/pulsar","slug":"invalid-retention-policy-type-s-valid-options-434e1d","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/CmdTopicPolicies.java","lineNumber":1055,"sourceCode":"                + \"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        @Option(names = { \"--global\", \"-g\" }, description = \"Whether to set this policy globally. \"\n                + \"If set to true, the policy will be replicate to other clusters asynchronously\")\n        private boolean isGlobal = false;\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            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            String persistentTopic = validatePersistentTopic(topicName);\n            BacklogQuota.Builder builder = BacklogQuota.builder().retentionPolicy(policy);\n\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                }\n                builder.limitSize(limit);\n            } else {","sourceCodeStart":1037,"sourceCodeEnd":1073,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-client-tools/src/main/java/org/apache/pulsar/admin/cli/CmdTopicPolicies.java#L1037-L1073","documentation":"Thrown when setting a backlog quota: the retention policy string cannot be parsed as a BacklogQuota.RetentionPolicy enum constant (or, in the same command, the quota type fails similarly). The valid retention policies are Limit (formerly consumer_backlog_eviction) and RequestTime... precisely the enum constants printed in the message, so the CLI surfaces them for self-correction.","triggerScenarios":"Running `pulsar-admin namespaces set-backlog-quota` (topic-policies equivalent) with --policy set to something other than an exact RetentionPolicy constant, e.g. 'evict' or lowercase 'limit'.","commonSituations":"Older documentation using legacy policy names, lowercase enum spellings, typos, or confusing RetentionPolicy with BacklogQuotaType in the flag order.","solutions":["Use exact enum values, e.g. consumer_backlog_eviction or request_time_out (see the message's list for your version)","Match capitalization and underscores exactly","Check you passed the policy string to --policy and the quota type to --type, not swapped","Consult Arrays.toString(RetentionPolicy.values()) output in the error for the authoritative set"],"exampleFix":"// before\n--policy limit\n// after\n--policy consumer_backlog_eviction","handlingStrategy":"validation","validationCode":"BacklogQuota.RetentionPolicy.valueOf(policyStr); // throws with valid options on failure\nBacklogQuota.BacklogQuotaType.valueOf(quotaTypeStr);","typeGuard":"boolean isValidRetentionPolicy(String s) {\n    for (BacklogQuota.RetentionPolicy p : BacklogQuota.RetentionPolicy.values()) {\n        if (p.name().equals(s)) return true;\n    }\n    return false;\n}","tryCatchPattern":"try {\n    admin.topicPolicies().setBacklogQuota(topic, quota, policyType);\n} catch (IllegalArgumentException e) {\n    System.err.println(\"Valid policies: \" + Arrays.toString(BacklogQuota.RetentionPolicy.values()));\n}","preventionTips":["Copy enum constant names directly from the error message's valid-options list","Do not use lowercase or legacy short names like 'limit'","Verify --policy and --type flags are not swapped","Pin automation scripts to a Pulsar version and re-check enum values after upgrades"],"tags":["pulsar-admin","cli","topic-policies","invalid-enum-value"],"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"}