alibaba/nacos · error · IllegalArgumentException

min cache time for http or tcp is too small(<10000)

Error message

min cache time for http or tcp is too small(<10000)

What it means

Thrown when entry is 'pushCacheMillis' and the parsed long value is below MIN_PUSH_CACHE_TIME_MIILIS (10000 ms). This controls the default cache duration for push-based (HTTP/TCP) client notifications; values below 10 seconds would flood clients with push traffic.

Source

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

                    tempSwitchDomain.setPushJavaVersion(version);
                } else if (StringUtils.equals(SwitchEntry.CLIENT_PYTHON, type)) {
                    tempSwitchDomain.setPushPythonVersion(version);
                } else if (StringUtils.equals(SwitchEntry.CLIENT_C, type)) {
                    tempSwitchDomain.setPushCVersion(version);
                } else if (StringUtils.equals(SwitchEntry.CLIENT_GO, type)) {
                    tempSwitchDomain.setPushGoVersion(version);
                } else if (StringUtils.equals(SwitchEntry.CLIENT_CSHARP, type)) {
                    tempSwitchDomain.setPushCSharpVersion(version);
                } else {
                    throw new IllegalArgumentException("unsupported client type: " + type);
                }
            }
            
            if (entry.equals(SwitchEntry.PUSH_CACHE_MILLIS)) {
                long cacheMillis = Long.parseLong(value);
                
                if (cacheMillis < SwitchEntry.MIN_PUSH_CACHE_TIME_MIILIS) {
                    throw new IllegalArgumentException(
                        "min cache time for http or tcp is too small(<10000)");
                }
                
                tempSwitchDomain.setDefaultPushCacheMillis(cacheMillis);
            }
            
            // extremely careful while modifying this, cause it will affect all clients without pushing enabled
            if (entry.equals(SwitchEntry.DEFAULT_CACHE_MILLIS)) {
                long cacheMillis = Long.parseLong(value);
                
                if (cacheMillis < SwitchEntry.MIN_CACHE_TIME_MIILIS) {
                    throw new IllegalArgumentException(
                        "min default cache time  is too small(<1000)");
                }
                
                tempSwitchDomain.setDefaultCacheMillis(cacheMillis);
            }
            

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Set pushCacheMillis to >= 10000 (10 seconds).
2. Remember the value is in milliseconds, not seconds.
3. If you need faster pushes, tune the client-side cache instead of lowering this server-side floor.

Example fix

// before
PUT /v3/admin/ns/operator/switches?entry=pushCacheMillis&value=5000
// after
PUT /v3/admin/ns/operator/switches?entry=pushCacheMillis&value=10000

long cacheMillis = Long.parseLong(value);
if (cacheMillis < 10000) {
    throw new IllegalArgumentException("pushCacheMillis must be >= 10000");
}

function isValidPushCacheMillis(v: number): boolean {
  return v >= 10000;
}

try {
  operatorV2Impl.updateSwitch("pushCacheMillis", String.valueOf(cacheMillis), debug);
} catch (NacosApiException e) {
  if (e.getMessage().contains("too small")) {
    cacheMillis = 10000; // clamp to minimum
  }
}

When it happens

Trigger: PUT /v3/admin/ns/operator/switches with entry=pushCacheMillis and value < 10000, e.g. value=5000, value=9999, value=0.

Common situations: Confusing units (passing seconds instead of milliseconds), or attempting aggressive push tuning without understanding the minimum safety floor.

Related errors

• min default cache time is too small(<1000)
• 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/4f81d06adcf88908. Report an issue: GitHub.