alibaba/nacos · warning · NacosApiException

23000

23000

Error message

Illegal state: {state}

What it means

Thrown by GET /v3/admin/core/cluster/node/list when the optional 'state' query parameter cannot be parsed into a NodeState enum constant (after upper-casing). Valid NodeState values are STARTING, UP, SUSPICIOUS, DOWN, ISOLATION (case-insensitive). Maps to NacosApiException with ErrorCode.ILLEGAL_STATE (code 23000) and HTTP 400.

Source

Thrown at core/src/main/java/com/alibaba/nacos/core/controller/v3/NacosClusterControllerV3.java:95

     *
     * @param address match address
     * @param state   match state
     * @return members that matches condition
     */
    @Since("3.0.0")
    @GetMapping(value = "/node/list")
    @Secured(action = ActionTypes.READ, resource = NACOS_ADMIN_CORE_CONTEXT_V3
        + "/cluster", signType = SignType.CONSOLE, apiType = ApiType.ADMIN_API)
    public Result<Collection<Member>> listNodes(
        @RequestParam(value = "address", required = false) String address,
        @RequestParam(value = "state", required = false) String state) throws NacosException {
        
        NodeState nodeState = null;
        if (StringUtils.isNoneBlank(state)) {
            try {
                nodeState = NodeState.valueOf(state.toUpperCase(Locale.ROOT));
            } catch (IllegalArgumentException e) {
                throw new NacosApiException(HttpStatus.BAD_REQUEST.value(), ErrorCode.ILLEGAL_STATE,
                    "Illegal state: " + state);
            }
        }
        return Result.success(nacosClusterOperationService.listNodes(address, nodeState));
    }
    
    /**
     * Other nodes return their own metadata information.
     *
     * @param nodes List of {@link Member}
     * @return {@link RestResult}
     */
    @Since("3.0.0")
    @PutMapping(value = "/node/list")
    @Secured(action = ActionTypes.WRITE, resource = NACOS_ADMIN_CORE_CONTEXT_V3
        + "/cluster", signType = SignType.CONSOLE, apiType = ApiType.ADMIN_API)
    public Result<Boolean> updateNodes(@RequestBody List<Member> nodes) throws NacosApiException {
        if (nodes == null || nodes.isEmpty()) {

View on GitHub (pinned to 9b989acdf1)

Solutions

  1. Use one of the supported state values (case-insensitive): starting, up, suspicious, down, isolation.
  2. Omit the state parameter entirely to list nodes in any state.
  3. Update the calling tool/console to the documented enum values.

Example fix

// before
GET /v3/admin/core/cluster/node/list?state=online

// after
GET /v3/admin/core/cluster/node/list?state=up
Defensive patterns

Strategy: validation

Validate before calling

Set<String> VALID = Arrays.stream(NodeState.values())
    .map(Enum::name).map(String::toLowerCase).collect(Collectors.toSet());
if (state != null && !VALID.contains(state.toLowerCase(Locale.ROOT))) {
    // reject before calling the API
}

Try / catch

try {
    restTemplate.getForObject("/node/list?state=" + state, ...);
} catch (NacosApiException e) {
    if (e.getErrCode() == ErrorCode.ILLEGAL_STATE.getCode()) { /* bad state value */ }
}

Prevention

When it happens

Trigger: Passing state=online, state=ready, state=alive, or any string that is not one of the five NodeState names. NodeState.valueOf throws IllegalArgumentException which is caught and rethrown as this NacosApiException.

Common situations: Operator/console uses an intuitive but unsupported state name; documentation mismatch; scripting the cluster node-list API with a guessed state value.

Related errors

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