apache/shardingsphere · error · IllegalArgumentException

System property `%s` must be a positive integer, but was `%s

Error message

System property `%s` must be a positive integer, but was `%s`.

What it means

Thrown by MCPRuntimeProtectionPolicy.getPositiveIntegerProperty when a system property that tunes runtime protection limits (e.g. max completion requests per minute) is set but is either not parsable as an integer (NumberFormatException path, with cause attached) or parses to a value <= 0 (checkState path). The property name and the offending value are both included in the message.

Source

Thrown at mcp/support/src/main/java/org/apache/shardingsphere/mcp/support/security/MCPRuntimeProtectionPolicy.java:77

    /**
     * Get maximum completion requests per minute for one MCP session.
     *
     * @return maximum completion requests per minute
     */
    public static int getMaxCompletionRequestsPerMinute() {
        return getPositiveIntegerProperty(MAX_COMPLETION_REQUESTS_PER_MINUTE_PROPERTY, DEFAULT_MAX_COMPLETION_REQUESTS_PER_MINUTE);
    }
    
    private static int getPositiveIntegerProperty(final String propertyName, final int defaultValue) {
        String configuredValue = System.getProperty(propertyName);
        if (null == configuredValue) {
            return defaultValue;
        }
        int result;
        try {
            result = Integer.parseInt(configuredValue);
        } catch (final NumberFormatException ex) {
            throw new IllegalArgumentException(String.format("System property `%s` must be a positive integer, but was `%s`.", propertyName, configuredValue), ex);
        }
        ShardingSpherePreconditions.checkState(result > 0,
                () -> new IllegalArgumentException(String.format("System property `%s` must be a positive integer, but was `%s`.", propertyName, configuredValue)));
        return result;
    }
    
    /**
     * Create tool call limit payload.
     *
     * @return tool call limit payload
     */
    public static Map<String, Object> createToolCallLimitPayload() {
        Map<String, Object> result = new LinkedHashMap<>(4, 1F);
        result.put("scope", "session");
        result.put("max_calls", getMaxToolCallsPerSession());
        result.put("property", MAX_TOOL_CALLS_PER_SESSION_PROPERTY);
        result.put(MCPPayloadFieldNames.RECOVERY, "Close and recreate the MCP session after the quota is exhausted.");
        return result;

View on GitHub (pinned to e952770a21)

Solutions

  1. Fix the -D value to a positive integer, e.g. -D<property>=60.
  2. Remove the property to use the built-in default if you do not need a custom limit.
  3. Check for trailing whitespace/quotes in the JVM argument (shell quoting artifacts often land in the value, and the message shows the exact offending string).

Example fix

# before
export JAVA_TOOL_OPTIONS="-Dmcp.max.completion.requests.per.minute=0"
# after
export JAVA_TOOL_OPTIONS="-Dmcp.max.completion.requests.per.minute=60"
Defensive patterns

Strategy: validation

Validate before calling

String v = System.getProperty(propertyName);
if (null != v && !v.trim().matches("[1-9]\\d*")) throw new IllegalArgumentException(propertyName + " must be a positive integer: " + v);

Try / catch

try {
    MCPRuntimeProtectionPolicy.getMaxCompletionRequestsPerMinute();
} catch (final IllegalArgumentException ex) {
    // startup-time: fix or remove the -D flag named in the message and restart
}

Prevention

When it happens

Trigger: Starting the MCP server with -Dmcp.<limit-property>=abc, =10.5, =-1, or =0 (with the exact property name from the constant, e.g. MAX_COMPLETION_REQUESTS_PER_MINUTE_PROPERTY). Unset properties are fine — the code default is used.

Common situations: Tuning rate-limit properties via JAVA_OPTS or JVM flags with a typo or wrong format (percent signs, decimals, empty string), or copying a 0 from a config that intended 'unlimited' — this policy treats non-positive as invalid by design.

Related errors

AI-assisted analysis of apache/shardingsphere@e952770a21 (2026-08-14). Data as JSON: /api/errors/2f913323e171d64c. Report an issue: GitHub.