{"record":{"id":"df89ba645239f36e","repo":"apache/pulsar","slug":"the-retention-size-must-the-backlog-quota-limit","errorCode":null,"errorMessage":"The retention size must > the backlog quota limit size, but the configured backlog quota limit bytes is %d, the retention size is %d","messagePattern":"The retention size must > the backlog quota limit size, but the configured backlog quota limit bytes is (.+?), the retention size is (.+?)","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"pulsar-broker/src/main/java/org/apache/pulsar/broker/PulsarService.java","lineNumber":890,"sourceCode":"            }\n\n            if (config.getWebServicePort().isEmpty()\n                    && config.getWebServicePortTls().isEmpty()\n                    && BindAddressValidator.validateBindAddresses(config, Arrays.asList(\"http\", \"https\")).isEmpty()) {\n                throw new IllegalArgumentException(\n                        \"webServicePort/webServicePortTls or http/https bindAddresses must be present\");\n            }\n\n            if (config.isAuthorizationEnabled() && !config.isAuthenticationEnabled()) {\n                throw new IllegalStateException(\"Invalid broker configuration. Authentication must be enabled with \"\n                        + \"authenticationEnabled=true when authorization is enabled with authorizationEnabled=true.\");\n            }\n\n            if (config.getDefaultRetentionSizeInMB() > 0\n                    && config.getBacklogQuotaDefaultLimitBytes() > 0\n                    && config.getBacklogQuotaDefaultLimitBytes()\n                    >= (config.getDefaultRetentionSizeInMB() * 1024L * 1024L)) {\n                throw new IllegalArgumentException(String.format(\"The retention size must > the backlog quota limit \"\n                                + \"size, but the configured backlog quota limit bytes is %d, the retention size is %d\",\n                        config.getBacklogQuotaDefaultLimitBytes(),\n                        config.getDefaultRetentionSizeInMB() * 1024L * 1024L));\n            }\n\n            if (config.getDefaultRetentionTimeInMinutes() > 0\n                    && config.getBacklogQuotaDefaultLimitSecond() > 0\n                    && config.getBacklogQuotaDefaultLimitSecond() >= config.getDefaultRetentionTimeInMinutes() * 60) {\n                throw new IllegalArgumentException(String.format(\"The retention time must > the backlog quota limit \"\n                                + \"time, but the configured backlog quota limit time duration is %d, \"\n                                + \"the retention time duration is %d\",\n                        config.getBacklogQuotaDefaultLimitSecond(),\n                        config.getDefaultRetentionTimeInMinutes() * 60));\n            }\n\n            if (config.isBrokerDeleteInactiveTopicsEnabled() && config.isBrokerCloseInactiveTopicsEnabled()) {\n                throw new IllegalArgumentException(\n                        \"brokerDeleteInactiveTopicsEnabled and brokerCloseInactiveTopicsEnabled are mutually \"","sourceCodeStart":872,"sourceCodeEnd":908,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-broker/src/main/java/org/apache/pulsar/broker/PulsarService.java#L872-L908","documentation":"This IllegalArgumentException is thrown at broker startup when the default backlog quota size limit is greater than or equal to the default retention size. Pulsar requires retention size to be strictly larger than the backlog quota limit, otherwise retention (which can only run when a topic is under quota) would never be able to delete data before the backlog quota stops producers. It is a fail-fast configuration sanity check performed by PulsarService.start().","triggerScenarios":"Starting a broker whose service configuration has defaultRetentionSizeInMB > 0, backlogQuotaDefaultLimitBytes > 0, and backlogQuotaDefaultLimitBytes >= defaultRetentionSizeInMB * 1024 * 1024 (e.g. retentionSizeInMB=1 with backlogQuotaDefaultLimitBytes=1073741824).","commonSituations":"Operators set a generous default backlog quota (e.g. 1GB) while leaving a small default retention size (e.g. 1MB), or tune backlogQuotaDefaultLimitBytes without re-checking retentionSizeInMB, so the broker refuses to boot.","solutions":["Increase defaultRetentionSizeInMB (or lower backlogQuotaDefaultLimitBytes) so retention size in bytes is strictly greater than the backlog quota limit bytes.","If retention should be effectively unlimited, set backlogQuotaDefaultLimitBytes to -1 (disabled) so the check is skipped.","Set defaultRetentionSizeInMB to -1 (disabled) if you want quota-only eviction without size-based retention.","Align the defaults in broker.conf / pulsar.znc configuration and restart the broker."],"exampleFix":"// before (broker.conf)\ndefaultRetentionSizeInMB=1\nbacklogQuotaDefaultLimitBytes=1073741824\n// after\ndefaultRetentionSizeInMB=2048\nbacklogQuotaDefaultLimitBytes=1073741824","handlingStrategy":"validation","validationCode":"// before broker start (Java)\nif (conf.getDefaultRetentionSizeInMB() > 0 && conf.getBacklogQuotaDefaultLimitBytes() > 0\n        && conf.getBacklogQuotaDefaultLimitBytes() >= conf.getDefaultRetentionSizeInMB() * 1024L * 1024L) {\n    throw new IllegalArgumentException(\n        \"backlogQuotaDefaultLimitBytes must be < defaultRetentionSizeInMB * 1024 * 1024 (or disabled)\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    pulsar.start();\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().contains(\"retention size must > the backlog quota limit\")) {\n        // fix broker.conf: raise retention size or lower/disable backlogQuotaDefaultLimitBytes, then retry\n    } else {\n        throw e;\n    }\n}","preventionTips":["Keep defaultRetentionSizeInMB strictly larger than backlogQuotaDefaultLimitBytes / 1MB in broker.conf.","Add the size comparison to your configuration CI/lint checks before deploying broker configs.","Disable one side (-1) when you intend quota-only or retention-only behavior.","Re-check the pair whenever you tune backlog quotas; they are validated against retention at startup."],"tags":["broker","configuration","startup","backlog-quota","retention"],"backgroundTag":"invalid-configuration","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"}