alibaba/nacos · error · NacosApiException

PARAMETER_VALIDATE_ERROR

PARAMETER_VALIDATE_ERROR

Error message

Unsupported ARD federation mode: " + federation

What it means

Thrown by validateAndBuildContext() when the federation value is not one of the three allowed modes. After defaulting a blank federation to AUTO, the value must be in {FEDERATION_AUTO, FEDERATION_REFERRALS, FEDERATION_NONE}. Any other string yields PARAMETER_VALIDATE_ERROR (HTTP 400).

Source

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

            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();
        context.text = query.getText().trim();
        context.filter = filter;
        context.pageSize = normalizePageSize(request.getPageSize());
        context.pageToken = request.getPageToken();
        context.kinds = resolveKinds(filter);
        context.resourceTypes = resourceTypes(context.kinds);
        return context;
    }

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Use one of "auto", "referrals", or "none" (match the exact ArdProtocolConstants spelling).
2. Leave federation unset/null to accept the default (auto).
3. If unsure of the exact token, check ArdProtocolConstants.FEDERATION_* constant values.
4. Add a client-side enum validation against the allowed set before the request.

Example fix

// before
req.setFederation("all");

// after
req.setFederation("auto"); // auto | referrals | none

private static final Set<String> FEDERATION_MODES =
    Set.of("auto", "referrals", "none");

public String normalizeFederation(String federation) {
    if (federation == null || federation.trim().isEmpty()) {
        return "auto";
    }
    String f = federation.trim();
    if (!FEDERATION_MODES.contains(f)) {
        throw new IllegalArgumentException(
            "federation must be one of " + FEDERATION_MODES + ", got: " + f);
    }
    return f;
}

boolean isValidFederation(String f) {
    return f == null || Set.of("auto", "referrals", "none").contains(f.trim());
}

When it happens

Trigger: Sending ArdSearchRequest.federation as an unrecognized token such as "all", "true", "yes", "remote", or a typo like "referral" (missing the 's'). The comparison is exact against the ArdProtocolConstants strings (case-sensitive after trim).

Common situations: Client guesses a federation mode name not in the spec; a config flag is forwarded verbatim without mapping; documentation drift where the client expects more modes than implemented; trailing/leading spaces avoided by trim but wrong casing still fails.

Related errors

• PARAMETER_VALIDATE_ERROR
• PARAMETER_MISSING
• 400
• PARAMETER_MISMATCH
• DATA_ACCESS_ERROR

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