alibaba/nacos · error · IllegalArgumentException

json param invalid.

Error message

json param invalid.

What it means

Thrown when entry is httpHealthParams, tcpHealthParams, or mysqlHealthParams and Jackson deserialization (JacksonUtils.toObj) fails with a NacosDeserializationException. The value must be a valid JSON object matching the HealthParams structure (with min, max, factor fields). Note: only http and tcp params are validated post-deserialization; mysql params are not.

Source

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

            try {
                if (SwitchEntry.HTTP_HEALTH_PARAMS.equals(entry)) {
                    SwitchDomain.HttpHealthParams httpHealthParams =
                        JacksonUtils.toObj(value, SwitchDomain.HttpHealthParams.class);
                    tempSwitchDomain.setHttpHealthParams(httpHealthParams);
                    validateHealthParams(httpHealthParams);
                }
                if (SwitchEntry.TCP_HEALTH_PARAMS.equals(entry)) {
                    SwitchDomain.TcpHealthParams tcpHealthParams =
                        JacksonUtils.toObj(value, SwitchDomain.TcpHealthParams.class);
                    tempSwitchDomain.setTcpHealthParams(tcpHealthParams);
                    validateHealthParams(tcpHealthParams);
                }
                if (SwitchEntry.MYSQL_HEALTH_PARAMS.equals(entry)) {
                    tempSwitchDomain.setMysqlHealthParams(
                        JacksonUtils.toObj(value, SwitchDomain.MysqlHealthParams.class));
                }
            } catch (NacosDeserializationException e) {
                throw new IllegalArgumentException("json param invalid.");
            }
            
            if (debug) {
                update(tempSwitchDomain);
            } else {
                updateWithConsistency(tempSwitchDomain);
            }
            
        } finally {
            this.requestLock.unlock();
        }
        
    }
    
    /**
     * Update switch information from new switch domain.
     *
     * @param newSwitchDomain new switch domain

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Provide a complete JSON object with double-quoted keys: {"min":500,"max":5000,"factor":0.85}.
2. Validate the JSON with a parser before sending.
3. For http/tcp params, also ensure min >= 500, max >= 3000, and 0 <= factor <= 1.

Example fix

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

try {
    objectMapper.readTree(value); // validate JSON parseability
} catch (Exception e) {
    throw new IllegalArgumentException("Health params value is not valid JSON");
}

function isValidHealthParamsJson(value: string): boolean {
  try {
    const obj = JSON.parse(value);
    return typeof obj === 'object' && obj !== null;
  } catch { return false; }
}

try {
  operatorV2Impl.updateSwitch(entry, value, debug);
} catch (NacosApiException e) {
  if (e.getMessage().contains("json param invalid")) {
    // re-serialize the health params object to proper JSON
  }
}

When it happens

Trigger: PUT /v3/admin/ns/operator/switches with entry=httpHealthParams and a malformed JSON value, e.g. value='{', value='{min:}', value='not json'.

Common situations: Passing a plain string or truncated JSON, using single quotes instead of double quotes, or missing required fields.

Related errors

• min check time for http or tcp is too small(<500)
• max check time for http or tcp is too small(<3000)
• 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/a327e798cf797d9b. Report an issue: GitHub.