alibaba/nacos · error · IllegalArgumentException

serverStatusSynchronizationPeriodMillis is too small(<15000)

Error message

serverStatusSynchronizationPeriodMillis is too small(<15000)

What it means

Thrown when entry is 'serverStatusSynchronizationPeriodMillis' and the parsed long is below MIN_SERVER_SYNC_TIME_MIILIS (1000 ms). WARNING: the error message says '<15000' but the actual constant is 1000 (SwitchEntry.MIN_SERVER_SYNC_TIME_MIILIS = 1000) — the message is misleading and overstates the real threshold by 15x.

Source

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

                tempSwitchDomain.setPushEnabled(enabled);
            }
            
            if (entry.equals(SwitchEntry.SERVICE_STATUS_SYNC_PERIOD)) {
                long millis = Long.parseLong(value);
                
                if (millis < SwitchEntry.MIN_SERVICE_SYNC_TIME_MIILIS) {
                    throw new IllegalArgumentException(
                        "serviceStatusSynchronizationPeriodMillis is too small(<5000)");
                }
                
                tempSwitchDomain.setServiceStatusSynchronizationPeriodMillis(millis);
            }
            
            if (entry.equals(SwitchEntry.SERVER_STATUS_SYNC_PERIOD)) {
                long millis = Long.parseLong(value);
                
                if (millis < SwitchEntry.MIN_SERVER_SYNC_TIME_MIILIS) {
                    throw new IllegalArgumentException(
                        "serverStatusSynchronizationPeriodMillis is too small(<15000)");
                }
                
                tempSwitchDomain.setServerStatusSynchronizationPeriodMillis(millis);
            }
            
            if (entry.equals(SwitchEntry.HEALTH_CHECK_TIMES)) {
                int times = Integer.parseInt(value);
                
                tempSwitchDomain.setCheckTimes(times);
            }
            
            if (entry.equals(SwitchEntry.DISABLE_ADD_IP)) {
                boolean disableAddIp = Boolean.parseBoolean(value);
                
                tempSwitchDomain.setDisableAddIP(disableAddIp);
            }
            

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Set serverStatusSynchronizationPeriodMillis to >= 1000 (1 second), NOT 15000 as the message implies.
2. Be aware the error message is inaccurate — the real floor is 1000ms.
3. File or track the message-vs-constant discrepancy as a doc bug.

Example fix

// before: user sets 15001 based on misleading message
PUT /v3/admin/ns/operator/switches?entry=serverStatusSynchronizationPeriodMillis&value=15001
// after: 1001 is sufficient; real minimum is 1000ms
PUT /v3/admin/ns/operator/switches?entry=serverStatusSynchronizationPeriodMillis&value=5000

long millis = Long.parseLong(value);
// NOTE: actual minimum is 1000, despite the error message saying <15000
if (millis < 1000) {
    throw new IllegalArgumentException("serverStatusSyncPeriod must be >= 1000 (actual floor, not 15000)");
}

function isValidServerStatusSyncPeriod(v: number): boolean {
  return v >= 1000; // actual constant, NOT 15000 as message claims
}

try {
  operatorV2Impl.updateSwitch("serverStatusSynchronizationPeriodMillis", String.valueOf(millis), debug);
} catch (NacosApiException e) {
  // message says <15000 but actual floor is 1000
  if (e.getMessage().contains("too small")) {
    millis = 5000;
  }
}

When it happens

Trigger: PUT /v3/admin/ns/operator/switches with entry=serverStatusSynchronizationPeriodMillis and value < 1000. Note: the message claims the floor is 15000 but the actual floor is 1000.

Common situations: Trusting the error message literally and setting value=15001 when the real minimum is 1001. Passing seconds instead of milliseconds. Encountering the misleading message during debugging.

Related errors

• serviceStatusSynchronizationPeriodMillis is too small(<5000)
• distroThreshold can not be zero or negative: {threshold}
• illegal format, must be 'type:version', but got: {value}
• illegal version, must match: {UtilsAndCommons.VERSION_STRING
• unsupported client type: {type}

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