apache/pulsar · error · IllegalArgumentException

Malformed configuration parameter: earlyTokenRefreshPercent

Error message

Malformed configuration parameter: earlyTokenRefreshPercent

What it means

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.

Source

Thrown at pulsar-client/src/main/java/org/apache/pulsar/client/impl/auth/oauth2/AuthenticationOAuth2.java:236

     * @param value the raw string from the configuration map
     * @return the resolved fractional percent, must be > 0
     * @throws IllegalArgumentException if the value cannot be parsed or is ≤ 0
     */
    static double parseEarlyRefreshPercent(String value) {
        try {
            double percent;
            if (value.contains(".")) {
                percent = Double.parseDouble(value);
            } else {
                percent = Integer.parseInt(value) / 100.0;
            }
            if (percent <= 0) {
                throw new IllegalArgumentException(
                        CONFIG_PARAM_EARLY_TOKEN_REFRESH_PERCENT + " must be greater than 0, got: " + value);
            }
            return percent;
        } catch (NumberFormatException e) {
            throw new IllegalArgumentException(
                    "Malformed configuration parameter: " + CONFIG_PARAM_EARLY_TOKEN_REFRESH_PERCENT, e);
        }
    }

    @Override
    @Deprecated
    public void configure(Map<String, String> authParams) {
        throw new NotImplementedException("Deprecated; use EncodedAuthenticationParameterSupport");
    }

    @Override
    public void start() throws PulsarClientException {
        flow.initialize();
    }

    /**
     * The first time that this method is called, it retrieves a token. All subsequent
     * calls should get a cached value. However, if there is an issue with the Identity

View on GitHub (pinned to 820761864e)

Solutions

1. Set earlyTokenRefreshPercent to a whole positive integer string, e.g. "20"
2. Remove the parameter entirely to use the default behavior
3. Trim whitespace and ensure no unit suffix (%, s) is present in the value

Example fix

// before
authParams.put("earlyTokenRefreshPercent", "12.5");
// after
authParams.put("earlyTokenRefreshPercent", "12");

String v = authParams.get("earlyTokenRefreshPercent");
if (v != null) {
    try {
        int p = Integer.parseInt(v.trim());
        if (p <= 0) throw new IllegalArgumentException("earlyTokenRefreshPercent must be > 0");
    } catch (NumberFormatException e) {
        throw new IllegalArgumentException("earlyTokenRefreshPercent must be an integer, got: " + v);
    }
}

boolean isValidRefreshPercent(String v) {
    if (v == null) return true;
    try { return Integer.parseInt(v.trim()) > 0; } catch (NumberFormatException e) { return false; }
}

try {
    auth.getAuthData();
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("earlyTokenRefreshPercent")) {
        log.warn("Bad earlyTokenRefreshPercent, using default", e);
    } else throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• earlyTokenRefreshPercent must be greater than 0.
• Required configuration parameters: tlsCertFile, tlsKeyFile
• Unsupported auth method: ${tokenEndpointAuthMethod}
• EarlyTokenRefreshPercent must be greater than 0.
• Unsupported auth method: ${authMethod}

AI-assisted analysis of apache/pulsar@820761864e (2026-09-06). Data as JSON: /api/errors/177afb88889db352. Report an issue: GitHub.