apache/dubbo · error · IllegalArgumentException

windowUpdateRatio must be > 0 and <= 1, but was: <windowUpda

Error message

windowUpdateRatio must be > 0 and <= 1, but was: <windowUpdateRatio>

What it means

Thrown by TripleConfig.setWindowUpdateRatio when the supplied ratio is outside the valid range (0, 1]. The window update ratio controls HTTP/2 flow-control update behavior for the Triple (gRPC-like) protocol, so values <= 0 or > 1 are rejected immediately on the setter. Null is allowed and means 'use default'.

Source

Thrown at dubbo-common/src/main/java/org/apache/dubbo/config/nested/TripleConfig.java:381

        return maxMessageSize == null ? DEFAULT_MAX_MESSAGE_SIZE : maxMessageSize;
    }

    public void setMaxMessageSize(Integer maxMessageSize) {
        this.maxMessageSize = maxMessageSize;
    }

    public Float getWindowUpdateRatio() {
        return windowUpdateRatio;
    }

    @Parameter(excluded = true)
    public float getWindowUpdateRatioOrDefault() {
        return windowUpdateRatio == null ? DEFAULT_WINDOW_UPDATE_RATIO : windowUpdateRatio;
    }

    public void setWindowUpdateRatio(Float windowUpdateRatio) {
        if (windowUpdateRatio != null && (windowUpdateRatio <= 0.0f || windowUpdateRatio > 1.0f)) {
            throw new IllegalArgumentException("windowUpdateRatio must be > 0 and <= 1, but was: " + windowUpdateRatio);
        }
        this.windowUpdateRatio = windowUpdateRatio;
    }

    public RestConfig getRest() {
        return rest;
    }

    @Parameter(excluded = true)
    public RestConfig getRestOrDefault() {
        if (rest == null) {
            rest = new RestConfig();
        }
        return rest;
    }

    public void setRest(RestConfig rest) {
        this.rest = rest;

View on GitHub (pinned to 3a3043227f)

Solutions

1. Set the ratio to a float strictly greater than 0 and less than or equal to 1 (e.g. 0.1 to 1.0).
2. Leave the property unset to use the default (DEFAULT_WINDOW_UPDATE_RATIO).
3. Double-check property source files (application.yml, dubbo.properties) for an out-of-range number.

Example fix

// before
tripleConfig.setWindowUpdateRatio(50f); // treated as 5000%

// after
tripleConfig.setWindowUpdateRatio(0.5f);

// Clamp/validate before setting
float ratio = ...;
if (ratio <= 0f || ratio > 1f) {
    throw new IllegalArgumentException("windowUpdateRatio must be in (0, 1], got: " + ratio);
}
tripleConfig.setWindowUpdateRatio(ratio);

static boolean isValidWindowUpdateRatio(Float r) {
    return r == null || (r > 0.0f && r <= 1.0f);
}

try {
    tripleConfig.setWindowUpdateRatio(parsedRatio);
} catch (IllegalArgumentException e) {
    // fall back to default and warn
    log.warn("Invalid windowUpdateRatio {}, using default", parsedRatio);
    tripleConfig.setWindowUpdateRatio(null);
}

When it happens

Trigger: Calling setWindowUpdateRatio with a Float value that is <= 0.0f or > 1.0f. Commonly happens via configuration properties (dubbo.provider.*.triple.window-update-ratio) parsed to an out-of-range number.

Common situations: Misunderstanding the ratio as a percentage (e.g. setting 50 meaning 50%) instead of a fraction (0.5). Typing the property as an integer > 1 in properties/YAML. Copying a value from a different flow-control setting with a different scale.

Related errors

• Invalid configurator rule, please specify at least one param
• service field in configuration is null.
• Arguments' types are different
• Illegal affinity rule!
• Illegal route rule!

AI-assisted analysis of apache/dubbo@3a3043227f (2026-08-14). Data as JSON: /api/errors/6e74dccd59650fee. Report an issue: GitHub.