alibaba/nacos · error · NacosApiException

20002

20002

Error message

invalid grayName : %s

What it means

Thrown by validateGrayName when grayName fails ParamUtils.isValid, which checks against Nacos's legal identifier pattern (typically [a-zA-Z0-9-_:\.]+ with no illegal/special chars). Returns HTTP 400 code 20002 (PARAMETER_VALIDATE_ERROR). The grayName is present but contains disallowed characters.

Source

Thrown at config/src/main/java/com/alibaba/nacos/config/server/controller/v3/ConfigControllerV3.java:564

    private void validateGrayForm(ConfigFormV3 configForm) throws NacosApiException {
        validateGrayName(configForm.getGrayName());
        if (StringUtils.isBlank(configForm.getGrayRuleExp())) {
            throw new NacosApiException(HttpStatus.BAD_REQUEST.value(), ErrorCode.PARAMETER_MISSING,
                "Required parameter 'grayRuleExp' type String is not present");
        }
        if (StringUtils.isBlank(configForm.getGrayVersion())) {
            throw new NacosApiException(HttpStatus.BAD_REQUEST.value(), ErrorCode.PARAMETER_MISSING,
                "Required parameter 'grayVersion' type String is not present");
        }
    }
    
    private void validateGrayName(String grayName) throws NacosApiException {
        if (StringUtils.isBlank(grayName)) {
            throw new NacosApiException(HttpStatus.BAD_REQUEST.value(), ErrorCode.PARAMETER_MISSING,
                "Required parameter 'grayName' type String is not present");
        }
        if (!ParamUtils.isValid(grayName.trim())) {
            throw new NacosApiException(HttpStatus.BAD_REQUEST.value(),
                ErrorCode.PARAMETER_VALIDATE_ERROR,
                "invalid grayName : " + grayName);
        }
    }
    
    /**
     * Execute import and publish config operation.
     */
    @Since("3.0.0")
    @PostMapping("/import")
    @Secured(action = ActionTypes.WRITE, signType = SignType.CONFIG, apiType = ApiType.ADMIN_API)
    public Result<Map<String, Object>> importAndPublishConfig(HttpServletRequest request,
        @RequestParam(value = "src_user", required = false) String srcUser,
        @RequestParam(value = "namespaceId", required = false) String namespaceId,
        @RequestParam(value = "policy", defaultValue = "ABORT") SameConfigPolicy policy,
        MultipartFile file)
        throws NacosException {
        Map<String, Object> failedData = new HashMap<>(4);

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Use only alphanumeric, dash, underscore, colon, and dot characters in grayName.
2. Trim whitespace before submitting.
3. Generate grayName from a safe slug function rather than raw user input.

Example fix

// before
grayName = "gray rule #1 / prod"
// after
grayName = "gray-rule-1-prod"

// Validate grayName matches allowed pattern before API call
private static final Pattern GRAY_NAME = Pattern.compile("[a-zA-Z0-9-_:\\.]+");
if (!GRAY_NAME.matcher(grayName.trim()).matches()) {
    throw new IllegalArgumentException("invalid grayName: " + grayName);
}

try { configApi.queryGray(form, grayName); }
catch (NacosApiException e) {
    if (e.getErrCode() == ErrorCode.PARAMETER_VALIDATE_ERROR.getCode())
        { /* sanitize grayName */ } else throw e;
}

When it happens

Trigger: Passing a grayName with spaces, slashes, Unicode characters, or other symbols not in the allowed character class [a-zA-Z0-9-_:\.]. Leading/trailing whitespace is trimmed before validation.

Common situations: Auto-generating grayName from a path or label containing slashes/spaces; copy-paste introducing hidden characters; using uppercase-only or reserved words.

Related errors

• 10000
• 400
• 400
• 400
• PARAMETER_VALIDATE_ERROR

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