{"record":{"id":"177afb88889db352","repo":"apache/pulsar","slug":"malformed-configuration-parameter-earlytokenrefre","errorCode":null,"errorMessage":"Malformed configuration parameter: earlyTokenRefreshPercent","messagePattern":"Malformed configuration parameter: earlyTokenRefreshPercent","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"pulsar-client/src/main/java/org/apache/pulsar/client/impl/auth/oauth2/AuthenticationOAuth2.java","lineNumber":236,"sourceCode":"     * @param value the raw string from the configuration map\n     * @return the resolved fractional percent, must be &gt; 0\n     * @throws IllegalArgumentException if the value cannot be parsed or is ≤ 0\n     */\n    static double parseEarlyRefreshPercent(String value) {\n        try {\n            double percent;\n            if (value.contains(\".\")) {\n                percent = Double.parseDouble(value);\n            } else {\n                percent = Integer.parseInt(value) / 100.0;\n            }\n            if (percent <= 0) {\n                throw new IllegalArgumentException(\n                        CONFIG_PARAM_EARLY_TOKEN_REFRESH_PERCENT + \" must be greater than 0, got: \" + value);\n            }\n            return percent;\n        } catch (NumberFormatException e) {\n            throw new IllegalArgumentException(\n                    \"Malformed configuration parameter: \" + CONFIG_PARAM_EARLY_TOKEN_REFRESH_PERCENT, e);\n        }\n    }\n\n    @Override\n    @Deprecated\n    public void configure(Map<String, String> authParams) {\n        throw new NotImplementedException(\"Deprecated; use EncodedAuthenticationParameterSupport\");\n    }\n\n    @Override\n    public void start() throws PulsarClientException {\n        flow.initialize();\n    }\n\n    /**\n     * The first time that this method is called, it retrieves a token. All subsequent\n     * calls should get a cached value. However, if there is an issue with the Identity","sourceCodeStart":218,"sourceCodeEnd":254,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-client/src/main/java/org/apache/pulsar/client/impl/auth/oauth2/AuthenticationOAuth2.java#L218-L254","documentation":"AuthenticationOAuth2 parses the optional earlyTokenRefreshPercent auth parameter via parseEarlyRefreshPercent. If the value cannot be parsed as a number, NumberFormatException is caught and rethrown as IllegalArgumentException('Malformed configuration parameter: earlyTokenRefreshPercent') with the original exception as cause. This guards against non-numeric strings being silently accepted for the background-refresh threshold.","triggerScenarios":"Passing authParam earlyTokenRefreshPercent with a non-integer value (e.g. \"50.5\", \"fifty\", \"\") to AuthenticationData or the client constructor; the NumberFormatException from Integer.parseInt is wrapped.","commonSituations":"Typo in YAML/properties config quoting the value with stray whitespace; using a decimal fraction (0.5) instead of a whole percentage (50); environment-variable interpolation yielding an empty string.","solutions":["Set earlyTokenRefreshPercent to a whole positive integer string, e.g. \"20\"","Remove the parameter entirely to use the default behavior","Trim whitespace and ensure no unit suffix (%, s) is present in the value"],"exampleFix":"// before\nauthParams.put(\"earlyTokenRefreshPercent\", \"12.5\");\n// after\nauthParams.put(\"earlyTokenRefreshPercent\", \"12\");","handlingStrategy":"validation","validationCode":"String v = authParams.get(\"earlyTokenRefreshPercent\");\nif (v != null) {\n    try {\n        int p = Integer.parseInt(v.trim());\n        if (p <= 0) throw new IllegalArgumentException(\"earlyTokenRefreshPercent must be > 0\");\n    } catch (NumberFormatException e) {\n        throw new IllegalArgumentException(\"earlyTokenRefreshPercent must be an integer, got: \" + v);\n    }\n}","typeGuard":"boolean isValidRefreshPercent(String v) {\n    if (v == null) return true;\n    try { return Integer.parseInt(v.trim()) > 0; } catch (NumberFormatException e) { return false; }\n}","tryCatchPattern":"try {\n    auth.getAuthData();\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().contains(\"earlyTokenRefreshPercent\")) {\n        log.warn(\"Bad earlyTokenRefreshPercent, using default\", e);\n    } else throw e;\n}","preventionTips":["Only pass whole-number strings (e.g. \"20\") for earlyTokenRefreshPercent","Trim and sanitize values read from env vars or YAML before passing","Validate the full authParams map in a startup smoke test"],"tags":["config","pulsar-client","oauth2"],"backgroundTag":"invalid-config-parameter","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"}