{"record":{"id":"e65377d6f93e2a3d","repo":"apache/pulsar","slug":"failoverthreshold-must-be-larger-than-0","errorCode":null,"errorMessage":"failoverThreshold must be larger than 0","messagePattern":"failoverThreshold must be larger than 0","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"pulsar-client/src/main/java/org/apache/pulsar/client/impl/SameAuthParamsLookupAutoClusterFailover.java","lineNumber":319,"sourceCode":"    public enum PulsarServiceState {\n        Healthy,\n        PreFail,\n        Failed,\n        PreRecover;\n    }\n\n    public static Builder builder() {\n        return new Builder();\n    }\n\n    public static class Builder {\n\n        private SameAuthParamsLookupAutoClusterFailover\n                sameAuthParamsLookupAutoClusterFailover = new SameAuthParamsLookupAutoClusterFailover();\n\n        public Builder failoverThreshold(int failoverThreshold) {\n            if (failoverThreshold < 1) {\n                throw new IllegalArgumentException(\"failoverThreshold must be larger than 0\");\n            }\n            sameAuthParamsLookupAutoClusterFailover.failoverThreshold = failoverThreshold;\n            return this;\n        }\n\n        public Builder recoverThreshold(int recoverThreshold) {\n            if (recoverThreshold < 1) {\n                throw new IllegalArgumentException(\"recoverThreshold must be larger than 0\");\n            }\n            sameAuthParamsLookupAutoClusterFailover.recoverThreshold = recoverThreshold;\n            return this;\n        }\n\n        public Builder checkHealthyIntervalMs(int checkHealthyIntervalMs) {\n            if (checkHealthyIntervalMs < 1) {\n                throw new IllegalArgumentException(\"checkHealthyIntervalMs must be larger than 0\");\n            }\n            sameAuthParamsLookupAutoClusterFailover.checkHealthyIntervalMs = checkHealthyIntervalMs;","sourceCodeStart":301,"sourceCodeEnd":337,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-client/src/main/java/org/apache/pulsar/client/impl/SameAuthParamsLookupAutoClusterFailover.java#L301-L337","documentation":"The Builder.failoverThreshold(int) setter validates that the failover threshold (the number of consecutive failed probes before switching to the backup cluster) is at least 1. Values below 1 make the failover logic meaningless, so an IllegalArgumentException is thrown.","triggerScenarios":"Calling failoverThreshold(0) or failoverThreshold(negative) while configuring SameAuthParamsLookupAutoClusterFailover via its Builder, typically from a parsed config value that defaulted to 0.","commonSituations":"Config file/CLI flag left unset so an int field deserializes to 0 and is passed straight through; off-by-one edits trying to 'disable' failover by setting the threshold to 0.","solutions":["Pass a positive integer (>= 1) to failoverThreshold.","In your config loading code, default unset values to a sane positive number (e.g. the documented default) before calling the builder.","Clamp or reject invalid values at your own configuration-validation layer with a clear message."],"exampleFix":"// before\nbuilder.failoverThreshold(config.getFailoverThreshold()); // 0 when unset\n\n// after\nint t = config.getFailoverThreshold() > 0 ? config.getFailoverThreshold() : 3;\nbuilder.failoverThreshold(t);","handlingStrategy":"validation","validationCode":"int failoverThreshold = cfg.getFailoverThreshold();\nif (failoverThreshold < 1) {\n    failoverThreshold = 3;\n}","typeGuard":null,"tryCatchPattern":"try {\n    builder.failoverThreshold(t);\n} catch (IllegalArgumentException e) {\n    log.warn(\"Invalid failoverThreshold, using default 3\", e);\n    builder.failoverThreshold(3);\n}","preventionTips":["Validate all numeric failover config at load time, before building the client.","Never pass raw 0-valued int fields from config objects straight into builders.","Use Integer config types that distinguish 'unset' from 0."],"tags":["pulsar-client","configuration","validation","illegal-argument"],"backgroundTag":"invalid-config-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"}