alibaba/nacos · error · IllegalArgumentException

serviceStatusSynchronizationPeriodMillis is too small(<5000)

Error message

serviceStatusSynchronizationPeriodMillis is too small(<5000)

What it means

Thrown when entry is 'serviceStatusSynchronizationPeriodMillis' and the parsed long is below MIN_SERVICE_SYNC_TIME_MIILIS (5000 ms). This controls how frequently service status is synchronized across the Distro cluster; too-frequent sync would overload inter-node communication.

Source

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

                boolean enabled = Boolean.parseBoolean(value);
                tempSwitchDomain.setDistroEnabled(enabled);
            }
            
            if (entry.equals(SwitchEntry.CHECK) || entry.equals(SwitchEntry.HEALTH_CHECK_ENABLED)) {
                boolean enabled = Boolean.parseBoolean(value);
                tempSwitchDomain.setHealthCheckEnabled(enabled);
            }
            
            if (entry.equals(SwitchEntry.PUSH_ENABLED)) {
                boolean enabled = Boolean.parseBoolean(value);
                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)) {

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Set serviceStatusSynchronizationPeriodMillis to >= 5000 (5 seconds).
2. Confirm the value is in milliseconds.

Example fix

// before
PUT /v3/admin/ns/operator/switches?entry=serviceStatusSynchronizationPeriodMillis&value=3000
// after
PUT /v3/admin/ns/operator/switches?entry=serviceStatusSynchronizationPeriodMillis&value=5000

long millis = Long.parseLong(value);
if (millis < 5000) {
    throw new IllegalArgumentException("serviceStatusSyncPeriod must be >= 5000");
}

function isValidServiceStatusSyncPeriod(v: number): boolean {
  return v >= 5000;
}

try {
  operatorV2Impl.updateSwitch("serviceStatusSynchronizationPeriodMillis", String.valueOf(millis), debug);
} catch (NacosApiException e) {
  if (e.getMessage().contains("too small")) {
    millis = 5000;
  }
}

When it happens

Trigger: PUT /v3/admin/ns/operator/switches with entry=serviceStatusSynchronizationPeriodMillis and value < 5000, e.g. value=3000, value=1000.

Common situations: Passing seconds instead of milliseconds, or attempting aggressive cluster sync tuning below the 5-second minimum.

Related errors

• serverStatusSynchronizationPeriodMillis is too small(<15000)
• 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/569498c2b76d24e1. Report an issue: GitHub.