When a message has been redelivered more than {@code maxRedeliverCount} times,\n * it is moved to the dead letter topic instead of being redelivered again.\n *\n *
Construct via {@link #builder()}.\n */\n@EqualsAndHashCode\n@ToString\npublic final class DeadLetterPolicy {\n\n private final int maxRedeliverCount;\n private final String retryLetterTopic;\n private final String deadLetterTopic;\n private final String initialSubscriptionName;\n\n private DeadLetterPolicy(int maxRedeliverCount, String retryLetterTopic,\n String deadLetterTopic, String initialSubscriptionName) {\n if (maxRedeliverCount < 0) {\n throw new IllegalArgumentException(\"maxRedeliverCount must be >= 0\");\n }\n this.maxRedeliverCount = maxRedeliverCount;\n this.retryLetterTopic = retryLetterTopic;\n this.deadLetterTopic = deadLetterTopic;\n this.initialSubscriptionName = initialSubscriptionName;\n }\n\n /**\n * @return the maximum number of redelivery attempts before sending to the dead letter topic\n */\n public int maxRedeliverCount() {\n return maxRedeliverCount;\n }\n\n /**\n * @return the custom retry letter topic, or {@code null} for the auto-generated default\n */\n public String retryLetterTopic() {","sourceCodeStart":26,"sourceCodeEnd":62,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-client-api-v5/src/main/java/org/apache/pulsar/client/api/v5/config/DeadLetterPolicy.java#L26-L62","documentation":"DeadLetterPolicy requires maxRedeliverCount >= 0 because it defines how many redelivery attempts occur before a message is routed to the dead-letter topic; 0 means immediate dead-lettering and negative values have no meaning. The constructor throws IllegalArgumentException for negative values.","triggerScenarios":"Calling DeadLetterPolicy.builder().maxRedeliverCount(-1) or passing a negative value computed from config; sentinel -1 used for 'unlimited' or 'unset'.","commonSituations":"Using -1 to mean 'never dead-letter' (unsupported semantics here); config parsing an empty string into a negative default; arithmetic on retry counters that can go negative.","solutions":["Set maxRedeliverCount to 0 or a positive integer (e.g. 3 for three redeliveries before DLQ).","If you meant 'unlimited redeliveries', do not use a negative number - omit dead-letter routing or use a large positive cap.","Clamp or reject negative config values at load time: Math.max(0, configuredCount)."],"exampleFix":"// before\nDeadLetterPolicy dlp = DeadLetterPolicy.builder()\n .maxRedeliverCount(-1) // IllegalArgumentException\n .build();\n\n// after\nDeadLetterPolicy dlp = DeadLetterPolicy.builder()\n .maxRedeliverCount(3)\n .build();","handlingStrategy":"validation","validationCode":"int count = cfg.maxRedeliverCount();\nif (count < 0) {\n throw new IllegalArgumentException(\"maxRedeliverCount must be >= 0, got: \" + count);\n}\nDeadLetterPolicy dlp = DeadLetterPolicy.builder().maxRedeliverCount(count).build();","typeGuard":"static boolean isValidMaxRedeliverCount(int v) { return v >= 0; }","tryCatchPattern":"try {\n dlp = DeadLetterPolicy.builder().maxRedeliverCount(cfg).build();\n} catch (IllegalArgumentException e) {\n log.warn(\"Invalid maxRedeliverCount, using default DLQ policy\", e);\n dlp = DeadLetterPolicy.builder().build();\n}","preventionTips":["Don't use -1 to mean 'unlimited'; this policy has no unlimited semantics.","Clamp config-derived retry counts with Math.max(0, value).","Validate DLQ settings at consumer construction time."],"tags":["java","configuration","dead-letter","redelivery","consumer"],"backgroundTag":"invalid-configuration-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"}