{"record":{"id":"0995940916bc4969","repo":"alibaba/nacos","slug":"parameter-validate-error-099594","errorCode":"PARAMETER_VALIDATE_ERROR","errorMessage":"Unsupported ARD federation mode: \" + federation","messagePattern":"Unsupported ARD federation mode: \" \\+ federation","errorType":"exception","errorClass":"NacosApiException","httpStatus":400,"severity":"error","filePath":"ai-registry-adaptor/src/main/java/com/alibaba/nacos/airegistry/service/ard/ArdSearchServiceImpl.java","lineNumber":342,"sourceCode":"            return EnvUtil.getProperty(key, defaultValue);\n        } catch (Exception ignored) {\n            return defaultValue;\n        }\n    }\n    \n    private SearchContext validateAndBuildContext(ArdSearchRequest request)\n        throws NacosApiException {\n        if (request == null || request.getQuery() == null\n            || StringUtils.isBlank(request.getQuery().getText())) {\n            throw new NacosApiException(NacosException.INVALID_PARAM,\n                ErrorCode.PARAMETER_MISSING, \"Required parameter `query.text` not present\");\n        }\n        String federation = StringUtils.isBlank(request.getFederation())\n            ? ArdProtocolConstants.FEDERATION_AUTO : request.getFederation().trim();\n        if (!Arrays.asList(ArdProtocolConstants.FEDERATION_AUTO,\n            ArdProtocolConstants.FEDERATION_REFERRALS,\n            ArdProtocolConstants.FEDERATION_NONE).contains(federation)) {\n            throw new NacosApiException(NacosException.INVALID_PARAM,\n                ErrorCode.PARAMETER_VALIDATE_ERROR,\n                \"Unsupported ARD federation mode: \" + federation);\n        }\n        ArdSearchQuery query = request.getQuery();\n        Map<String, List<String>> filter = normalizeFilter(query);\n        validateFilterKeys(filter.keySet());\n        SearchContext context = new SearchContext();\n        context.namespaceId = StringUtils.isBlank(request.getNamespaceId())\n            ? com.alibaba.nacos.api.common.Constants.DEFAULT_NAMESPACE_ID\n            : request.getNamespaceId();\n        context.text = query.getText().trim();\n        context.filter = filter;\n        context.pageSize = normalizePageSize(request.getPageSize());\n        context.pageToken = request.getPageToken();\n        context.kinds = resolveKinds(filter);\n        context.resourceTypes = resourceTypes(context.kinds);\n        return context;\n    }","sourceCodeStart":324,"sourceCodeEnd":360,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/ai-registry-adaptor/src/main/java/com/alibaba/nacos/airegistry/service/ard/ArdSearchServiceImpl.java#L324-L360","documentation":"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).","triggerScenarios":"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).","commonSituations":"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.","solutions":["Use one of \"auto\", \"referrals\", or \"none\" (match the exact ArdProtocolConstants spelling).","Leave federation unset/null to accept the default (auto).","If unsure of the exact token, check ArdProtocolConstants.FEDERATION_* constant values.","Add a client-side enum validation against the allowed set before the request."],"exampleFix":"// before\nreq.setFederation(\"all\");\n\n// after\nreq.setFederation(\"auto\"); // auto | referrals | none","handlingStrategy":"validation","validationCode":"private static final Set<String> FEDERATION_MODES =\n    Set.of(\"auto\", \"referrals\", \"none\");\n\npublic String normalizeFederation(String federation) {\n    if (federation == null || federation.trim().isEmpty()) {\n        return \"auto\";\n    }\n    String f = federation.trim();\n    if (!FEDERATION_MODES.contains(f)) {\n        throw new IllegalArgumentException(\n            \"federation must be one of \" + FEDERATION_MODES + \", got: \" + f);\n    }\n    return f;\n}","typeGuard":"boolean isValidFederation(String f) {\n    return f == null || Set.of(\"auto\", \"referrals\", \"none\").contains(f.trim());\n}","tryCatchPattern":null,"preventionTips":["Use a client-side enum constrained to auto/referrals/none.","Leave federation unset to accept the default (auto) when unsure.","Reference ArdProtocolConstants.FEDERATION_* for the canonical spelling."],"tags":["ard","ai-registry","search","federation","parameter-validation"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}