alibaba/nacos · warning · IllegalArgumentException

distroThreshold can not be zero or negative: {threshold}

Error message

distroThreshold can not be zero or negative: {threshold}

What it means

Thrown by SwitchManager.update when the 'distroThreshold' switch entry is parsed as a float and the result is <= 0. The exception is an IllegalArgumentException (not a NacosException), raised during a switch-update operation on the cloned SwitchDomain. The Distro consistency threshold must be strictly positive (it controls the fraction of healthy instances below which Distro protects a service).

Source

Thrown at naming/src/main/java/com/alibaba/nacos/naming/misc/SwitchManager.java:119

    /**
     * Update switch information.
     *
     * @param entry item entry of switch, {@link SwitchEntry}
     * @param value switch value
     * @param debug whether debug
     * @throws Exception exception
     */
    public void update(String entry, String value, boolean debug) throws Exception {
        
        this.requestLock.lock();
        try {
            
            SwitchDomain tempSwitchDomain = this.switchDomain.clone();
            
            if (entry.equals(SwitchEntry.DISTRO_THRESHOLD)) {
                float threshold = Float.parseFloat(value);
                if (threshold <= 0) {
                    throw new IllegalArgumentException(
                        "distroThreshold can not be zero or negative: " + threshold);
                }
                tempSwitchDomain.setDistroThreshold(threshold);
            }
            
            if (entry.equals(SwitchEntry.CLIENT_BEAT_INTERVAL)) {
                long clientBeatInterval = Long.parseLong(value);
                tempSwitchDomain.setClientBeatInterval(clientBeatInterval);
            }
            
            if (entry.equals(SwitchEntry.PUSH_VERSION)) {
                
                String[] parts = value.split(":");
                if (parts.length < 2) {
                    throw new IllegalArgumentException(
                        "illegal format, must be 'type:version', but got: " + value);
                }
                String type = parts[0];

View on GitHub (pinned to 9b989acdf1)

Solutions

  1. Provide a positive float between 0.0 (exclusive) and 1.0, e.g. '0.5' or '0.85' (typical production value).
  2. Validate the input string is a valid positive float before calling update.
  3. Review the Distro protection semantics — setting it too low disables instance protection; it should never be zero.

Example fix

// before
switchManager.update("distroThreshold", "0", false);

// after
switchManager.update("distroThreshold", "0.5", false);
Defensive patterns

Strategy: validation

Validate before calling

String value = "0.5"; // from operator input
float threshold = Float.parseFloat(value);
if (threshold <= 0) {
    throw new IllegalArgumentException("distroThreshold must be > 0");
}
switchManager.update("distroThreshold", value, false);

Try / catch

try {
    switchManager.update("distroThreshold", value, false);
} catch (IllegalArgumentException e) {
    // invalid threshold — log and reject the operation
    logger.error("Invalid distroThreshold: {}", value);
}

Prevention

When it happens

Trigger: Calling the switch-update API (or SwitchManager.update directly) with entry='distroThreshold' and a value of '0', a negative number like '-0.5', or a non-numeric string that Float.parseFloat rejects (though that would throw NumberFormatException first). The explicit <= 0 guard catches valid-but-invalid floats like 0.0f or -1.0f.

Common situations: Operator accidentally sets distroThreshold to 0 when trying to disable health protection. Misconfigured automation passing an empty or zero string. Attempting to tune the protection threshold without understanding its semantics.

Related errors

AI-assisted analysis of alibaba/nacos@9b989acdf1 (2026-08-14). Data as JSON: /api/errors/f9d8d50c209e8746. Report an issue: GitHub.