alibaba/nacos · error · IllegalArgumentException

max check time for http or tcp is too small(<3000)

Error message

max check time for http or tcp is too small(<3000)

What it means

Thrown by validateHealthParams when healthParams.getMax() < SwitchDomain.HttpHealthParams.MIN_MAX (3000 ms). This is the maximum health-check interval; values below 3000ms would make checks too aggressive. Applies to both http and tcp health params.

Source

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

        switchDomain.setEnableAuthentication(newSwitchDomain.isEnableAuthentication());
        switchDomain.setOverriddenServerStatus(newSwitchDomain.getOverriddenServerStatus());
        switchDomain.setDefaultInstanceEphemeral(newSwitchDomain.isDefaultInstanceEphemeral());
        switchDomain.setLightBeatEnabled(newSwitchDomain.isLightBeatEnabled());
    }
    
    /**
     * Validate health params.
     *
     * @param healthParams health params
     */
    public void validateHealthParams(SwitchDomain.HealthParams healthParams) {
        if (healthParams.getMin() < SwitchDomain.HttpHealthParams.MIN_MIN) {
            throw new IllegalArgumentException("min check time for http or tcp is too small(<500)");
        }
        
        if (healthParams.getMax() < SwitchDomain.HttpHealthParams.MIN_MAX) {
            
            throw new IllegalArgumentException(
                "max check time for http or tcp is too small(<3000)");
        }
        
        if (healthParams.getFactor() < 0 || healthParams.getFactor() > 1) {
            
            throw new IllegalArgumentException("malformed factor");
        }
    }
    
    private void updateWithConsistency(SwitchDomain tempSwitchDomain) throws NacosException {
        try {
            final BatchWriteRequest req = new BatchWriteRequest();
            String switchDomainKey = KeyBuilder.getSwitchDomainKey();
            Datum datum = Datum.createDatum(switchDomainKey, tempSwitchDomain);
            req.append(ByteUtils.toBytes(switchDomainKey), serializer.serialize(datum));
            WriteRequest operationLog = WriteRequest.newBuilder().setGroup(group())
                .setOperation(OldDataOperation.Write.getDesc())
                .setData(ByteString.copyFrom(serializer.serialize(req)))

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Set the 'max' field to >= 3000 (milliseconds).
2. Ensure max >= min >= 500.

Example fix

// before
PUT /v3/admin/ns/operator/switches?entry=tcpHealthParams&value={"min":500,"max":2000,"factor":0.85}
// after
PUT /v3/admin/ns/operator/switches?entry=tcpHealthParams&value={"min":500,"max":5000,"factor":0.85}

if (healthParams.getMax() < 3000) {
    throw new IllegalArgumentException("Health check max must be >= 3000ms");
}

function isValidMax(max: number): boolean {
  return max >= 3000;
}

try {
  operatorV2Impl.updateSwitch(entry, json, debug);
} catch (NacosApiException e) {
  if (e.getMessage().includes("max check time")) {
    params.max = 3000;
    json = JSON.stringify(params);
  }
}

When it happens

Trigger: PUT /v3/admin/ns/operator/switches with entry=httpHealthParams or tcpHealthParams and a valid JSON whose 'max' field is < 3000, e.g. {"min":500,"max":2000,"factor":0.85}.

Common situations: Setting max too low when trying to speed up health checks, or max < min.

Related errors

• json param invalid.
• min check time for http or tcp is too small(<500)
• malformed factor
• distroThreshold can not be zero or negative: {threshold}
• illegal format, must be 'type:version', but got: {value}

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