alibaba/nacos · error · NacosApiException

PARAMETER_MISMATCH

PARAMETER_MISMATCH

Error message

Parameter 'searchMode' must be " + Constants.MCP_LIST_SEARCH_BLUR + " or " + Constants.MCP_LIST_SEARCH_ACCURATE

What it means

ListServerForm constrains searchMode to two allowed values (Constants.MCP_LIST_SEARCH_BLUR and Constants.MCP_LIST_SEARCH_ACCURATE, i.e. "blur" and "accurate"). Any other non-empty value throws PARAMETER_MISMATCH (HTTP 400).

Source

Thrown at ai-registry-adaptor/src/main/java/com/alibaba/nacos/airegistry/form/ListServerForm.java:104

     */
    @Override
    public void validate() throws NacosApiException {
        if (offset < 0) {
            throw new NacosApiException(HttpStatus.BAD_REQUEST.value(),
                ErrorCode.PARAMETER_VALIDATE_ERROR,
                "Parameter 'offset' must >= 0");
        }
        
        if (limit > Constants.MAX_LIST_SIZE) {
            throw new NacosApiException(HttpStatus.BAD_REQUEST.value(),
                ErrorCode.PARAMETER_VALIDATE_ERROR,
                "Parameter 'limit' must <= 100");
        }
        
        if (StringUtils.isNotEmpty(searchMode)) {
            if (!Constants.MCP_LIST_SEARCH_BLUR.equals(searchMode)
                && !Constants.MCP_LIST_SEARCH_ACCURATE.equals(searchMode)) {
                throw new NacosApiException(HttpStatus.BAD_REQUEST.value(),
                    ErrorCode.PARAMETER_MISMATCH,
                    "Parameter 'searchMode' must be " + Constants.MCP_LIST_SEARCH_BLUR + " or "
                        + Constants.MCP_LIST_SEARCH_ACCURATE);
            }
        }
        
    }
}

View on GitHub (pinned to 9b989acdf1)

Solutions

Use exactly searchMode=blur or searchMode=accurate.
Omit searchMode entirely to use the server default rather than guessing.
Confirm the exact string values against Constants.MCP_LIST_SEARCH_BLUR/ACCURATE.

Example fix

// before
GET /servers?searchMode=fuzzy

// after
GET /servers?searchMode=blur

Defensive patterns

Strategy: validation

Validate before calling

Set<String> allowed = Set.of("blur", "accurate"); // MCP_LIST_SEARCH_BLUR/ACCURATE
String mode = StringUtils.isBlank(searchMode) ? null : (allowed.contains(searchMode) ? searchMode : null);
if (mode != null) uri.queryParam("searchMode", mode);

Prevention

Omit searchMode rather than guessing the enum value.
Match the exact lowercase strings blur/accurate.
Centralize allowed enum values in the client.

When it happens

Trigger: Calling the list-servers endpoint with ?searchMode=fuzzy, ?searchMode=exact, or any value other than blur/accurate.

Common situations: Guessing the enum values; passing a localized or uppercased string (the comparison is case-sensitive); leftover param from a different API.

Related errors

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