alibaba/nacos · error · NacosApiException

PARAMETER_MISSING

PARAMETER_MISSING

Error message

Required parameter `query.text` not present

What it means

Thrown by ArdSearchServiceImpl.validateAndBuildContext() when an ARD search request omits query.text. The validator rejects a null request, a null query, or a blank query.text with PARAMETER_MISSING (HTTP 400). query.text is the single mandatory field for a search call; without it the search cannot run.

Source

Thrown at ai-registry-adaptor/src/main/java/com/alibaba/nacos/airegistry/service/ard/ArdSearchServiceImpl.java:334

    }
    
    private String property(String key, String defaultValue) {
        String value = System.getProperty(key);
        if (StringUtils.isNotBlank(value)) {
            return value;
        }
        try {
            return EnvUtil.getProperty(key, defaultValue);
        } catch (Exception ignored) {
            return defaultValue;
        }
    }
    
    private SearchContext validateAndBuildContext(ArdSearchRequest request)
        throws NacosApiException {
        if (request == null || request.getQuery() == null
            || StringUtils.isBlank(request.getQuery().getText())) {
            throw new NacosApiException(NacosException.INVALID_PARAM,
                ErrorCode.PARAMETER_MISSING, "Required parameter `query.text` not present");
        }
        String federation = StringUtils.isBlank(request.getFederation())
            ? ArdProtocolConstants.FEDERATION_AUTO : request.getFederation().trim();
        if (!Arrays.asList(ArdProtocolConstants.FEDERATION_AUTO,
            ArdProtocolConstants.FEDERATION_REFERRALS,
            ArdProtocolConstants.FEDERATION_NONE).contains(federation)) {
            throw new NacosApiException(NacosException.INVALID_PARAM,
                ErrorCode.PARAMETER_VALIDATE_ERROR,
                "Unsupported ARD federation mode: " + federation);
        }
        ArdSearchQuery query = request.getQuery();
        Map<String, List<String>> filter = normalizeFilter(query);
        validateFilterKeys(filter.keySet());
        SearchContext context = new SearchContext();
        context.namespaceId = StringUtils.isBlank(request.getNamespaceId())
            ? com.alibaba.nacos.api.common.Constants.DEFAULT_NAMESPACE_ID
            : request.getNamespaceId();

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Ensure request.getQuery().getText() is a non-blank string before invoking search.
2. Validate the JSON payload includes "query": {"text": "..."} with a non-empty value.
3. If you only want to list/filter without text, use the list/explore endpoint instead of search.
4. Add a client-side precondition that throws early with a clearer message.

Example fix

// before
ArdSearchRequest req = new ArdSearchRequest();
req.setQuery(new ArdSearchQuery()); // text omitted
service.search(req);

// after
ArdSearchRequest req = new ArdSearchRequest();
ArdSearchQuery q = new ArdSearchQuery();
q.setText("mcp weather");
req.setQuery(q);
service.search(req);

public void validateSearchRequest(ArdSearchRequest request) {
    if (request == null || request.getQuery() == null
        || request.getQuery().getText() == null
        || request.getQuery().getText().trim().isEmpty()) {
        throw new IllegalArgumentException("query.text is required and must be non-blank");
    }
}

boolean hasSearchText(ArdSearchRequest r) {
    return r != null && r.getQuery() != null
        && r.getQuery().getText() != null
        && !r.getQuery().getText().trim().isEmpty();
}

When it happens

Trigger: POSTing an ArdSearchRequest whose query field is null, whose query.text is null/empty/whitespace, or sending a request body missing the query.text JSON path entirely. Any of these three null-checks triggers the same error.

Common situations: Client serializes only filters but forgets the free-text term; a JSON deserialization default leaves query.text null; an explore-style request is mistakenly routed to the search endpoint; a caller trims text to empty before sending.

Related errors

• 10000
• PARAMETER_MISMATCH
• PARAMETER_VALIDATE_ERROR
• 10000
• INVALID_PARAM

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