{"record":{"id":"947fd485cee2f2bc","repo":"apache/pulsar","slug":"earlytokenrefreshpercent-must-be-greater-than-0","errorCode":null,"errorMessage":"earlyTokenRefreshPercent must be greater than 0.","messagePattern":"earlyTokenRefreshPercent must be greater than 0\\.","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"pulsar-client/src/main/java/org/apache/pulsar/client/impl/auth/oauth2/AuthenticationFactoryOAuth2.java","lineNumber":282,"sourceCode":"            return this;\n        }\n\n        /**\n         * The fraction of the token's {@code expires_in} time at which the client starts attempting\n         * a background refresh. Must be greater than 0. Values &ge; 1 disable early refresh (the default).\n         *\n         * <p>For example, {@code 0.8} means the client will attempt to refresh after 80% of the\n         * token lifetime has elapsed, leaving a 20% buffer to tolerate a temporary OAuth server\n         * outage while the existing token is still valid. During an outage the client keeps retrying\n         * in the background with exponential backoff, continuing to serve requests with the current\n         * token until it actually expires.\n         *\n         * @param earlyTokenRefreshPercent fractional value in (0, 1) to enable, or &ge; 1 to disable\n         * @return the builder\n         */\n        public ClientCredentialsBuilder earlyTokenRefreshPercent(double earlyTokenRefreshPercent) {\n            if (earlyTokenRefreshPercent <= 0) {\n                throw new IllegalArgumentException(\"earlyTokenRefreshPercent must be greater than 0.\");\n            }\n            this.earlyTokenRefreshPercent = earlyTokenRefreshPercent;\n            return this;\n        }\n\n        /**\n         * Optional scheduler for background token refresh tasks. If not set and early refresh is\n         * enabled, a shared internal daemon-thread scheduler is used automatically.\n         * {@link AuthenticationOAuth2} will never shut down a caller-supplied scheduler.\n         *\n         * @param scheduler the scheduler to use for background token refresh\n         * @return the builder\n         */\n        public ClientCredentialsBuilder scheduler(ScheduledExecutorService scheduler) {\n            this.scheduler = scheduler;\n            return this;\n        }\n","sourceCodeStart":264,"sourceCodeEnd":300,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-client/src/main/java/org/apache/pulsar/client/impl/auth/oauth2/AuthenticationFactoryOAuth2.java#L264-L300","documentation":"AuthenticationFactoryOAuth2.ClientCredentialsBuilder.earlyTokenRefreshPercent() validates its argument before storing it. The value must be a positive fraction in (0, 1) to enable early refresh, or >= 1 to disable it; a value <= 0 is meaningless and throws this IllegalArgumentException immediately.","triggerScenarios":"Calling .earlyTokenRefreshPercent(0), .earlyTokenRefreshPercent(-0.1), or any other value <= 0 while building the OAuth2 authentication via the builder.","commonSituations":"Loading the refresh percentage from config/environment where an unset value defaults to 0; a config file intended to 'disable' early refresh uses 0 instead of >= 1 (e.g. 1 or 100); sign errors when converting a percentage.","solutions":["Pass a value in (0, 1) to enable, e.g. 0.2 for 20% of token lifetime.","To disable early refresh pass a value >= 1 (e.g. 1 or 100), not 0.","Guard config-sourced values: default to 1 (disabled) when the config key is missing or <= 0."],"exampleFix":"// before\nbuilder.earlyTokenRefreshPercent(cfg.getEarlyRefresh()); // 0 when unset -> throws\n// after\ndouble pct = cfg.getEarlyRefresh() > 0 ? cfg.getEarlyRefresh() : 1; // >=1 disables\nbuilder.earlyTokenRefreshPercent(pct);","handlingStrategy":"validation","validationCode":"double v = config.earlyTokenRefreshPercent();\nif (!(v > 0)) { // rejects 0, negative, NaN\n    throw new IllegalArgumentException(\"earlyTokenRefreshPercent must be > 0 (use >= 1 to disable)\");\n}\nbuilder.earlyTokenRefreshPercent(v);","typeGuard":null,"tryCatchPattern":"try {\n    builder.earlyTokenRefreshPercent(pct);\n} catch (IllegalArgumentException e) {\n    log.warn(\"Invalid earlyTokenRefreshPercent {}, falling back to disabled (1.0)\", pct);\n    builder.earlyTokenRefreshPercent(1.0);\n}","preventionTips":["Remember the semantics: (0,1) enables, >= 1 disables — never use 0.","Default missing config values to 1.0 (disabled), not 0.","Validate fractions from config files before passing them on."],"tags":["pulsar-client","oauth2","configuration","argument-validation"],"backgroundTag":"invalid-argument-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"}