alibaba/nacos · error · NacosApiException

20002

20002

Error message

Request parameter `search` should be `accurate` or `blur`.

What it means

Thrown by McpListForm.validate() when `search` is neither 'accurate' nor 'blur'. Note fillDefaultValue() sets search to 'accurate' when empty, so this error only fires when search is explicitly set to an invalid non-empty value. Comparison is case-insensitive. Maps to code 20002 (PARAMETER_VALIDATE_ERROR), HTTP 400.

Source

Thrown at ai/src/main/java/com/alibaba/nacos/ai/form/mcp/admin/McpListForm.java:46

 *
 * @author xiweng.yy
 */
public class McpListForm extends McpForm {
    
    /**
     * blur or accurate.
     */
    private String search;
    
    @Serial
    private static final long serialVersionUID = 9017621414114266178L;
    
    @Override
    public void validate() throws NacosApiException {
        fillDefaultValue();
        if (!Constants.MCP_LIST_SEARCH_ACCURATE.equalsIgnoreCase(search)
            && !Constants.MCP_LIST_SEARCH_BLUR.equalsIgnoreCase(search)) {
            throw new NacosApiException(NacosApiException.INVALID_PARAM,
                ErrorCode.PARAMETER_VALIDATE_ERROR,
                "Request parameter `search` should be `accurate` or `blur`.");
        }
    }
    
    @Override
    protected void fillDefaultValue() {
        super.fillDefaultValue();
        if (StringUtils.isEmpty(search)) {
            search = Constants.MCP_LIST_SEARCH_ACCURATE;
        }
    }
    
    public String getSearch() {
        return search;
    }
    
    public void setSearch(String search) {

View on GitHub (pinned to 9b989acdf1)

Solutions

Set search to accurate or blur (any case), or omit it entirely to get the default (accurate).
Audit the caller's search-mode mapping and align it to the two allowed values.

Example fix

// before (fails)
search=fuzzy
// after
search=blur

Defensive patterns

Strategy: validation

Validate before calling

if (search != null && !"accurate".equalsIgnoreCase(search) && !"blur".equalsIgnoreCase(search)) {
    throw new IllegalArgumentException("search must be accurate or blur");
}

Type guard

static boolean isValidSearch(String s) {
    return s == null || "accurate".equalsIgnoreCase(s) || "blur".equalsIgnoreCase(s);
}

Try / catch

catch (NacosApiException e) {
    if (e.getErrCode() == 20002 && e.getMessage().contains("search")) { /* use accurate/blur */ }
}

Prevention

Omit search to get the default (accurate).
Restrict the UI to the two allowed values.

When it happens

Trigger: Calling GET /v3/admin/ai/mcp/list with search=fuzzy, search=contains, search=1, or any value other than accurate/blur.

Common situations: Client passes a custom search-mode vocabulary; a numeric flag instead of the string enum; legacy caller from a version that defaulted differently.

Related errors

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