{"record":{"id":"9c0fb41440032e55","repo":"alibaba/nacos","slug":"20002-9c0fb4","errorCode":"20002","errorMessage":"invalid grayName : %s","messagePattern":"invalid grayName : (.+?)","errorType":"validation","errorClass":"NacosApiException","httpStatus":400,"severity":"error","filePath":"config/src/main/java/com/alibaba/nacos/config/server/controller/v3/ConfigControllerV3.java","lineNumber":564,"sourceCode":"    private void validateGrayForm(ConfigFormV3 configForm) throws NacosApiException {\n        validateGrayName(configForm.getGrayName());\n        if (StringUtils.isBlank(configForm.getGrayRuleExp())) {\n            throw new NacosApiException(HttpStatus.BAD_REQUEST.value(), ErrorCode.PARAMETER_MISSING,\n                \"Required parameter 'grayRuleExp' type String is not present\");\n        }\n        if (StringUtils.isBlank(configForm.getGrayVersion())) {\n            throw new NacosApiException(HttpStatus.BAD_REQUEST.value(), ErrorCode.PARAMETER_MISSING,\n                \"Required parameter 'grayVersion' type String is not present\");\n        }\n    }\n    \n    private void validateGrayName(String grayName) throws NacosApiException {\n        if (StringUtils.isBlank(grayName)) {\n            throw new NacosApiException(HttpStatus.BAD_REQUEST.value(), ErrorCode.PARAMETER_MISSING,\n                \"Required parameter 'grayName' type String is not present\");\n        }\n        if (!ParamUtils.isValid(grayName.trim())) {\n            throw new NacosApiException(HttpStatus.BAD_REQUEST.value(),\n                ErrorCode.PARAMETER_VALIDATE_ERROR,\n                \"invalid grayName : \" + grayName);\n        }\n    }\n    \n    /**\n     * Execute import and publish config operation.\n     */\n    @Since(\"3.0.0\")\n    @PostMapping(\"/import\")\n    @Secured(action = ActionTypes.WRITE, signType = SignType.CONFIG, apiType = ApiType.ADMIN_API)\n    public Result<Map<String, Object>> importAndPublishConfig(HttpServletRequest request,\n        @RequestParam(value = \"src_user\", required = false) String srcUser,\n        @RequestParam(value = \"namespaceId\", required = false) String namespaceId,\n        @RequestParam(value = \"policy\", defaultValue = \"ABORT\") SameConfigPolicy policy,\n        MultipartFile file)\n        throws NacosException {\n        Map<String, Object> failedData = new HashMap<>(4);","sourceCodeStart":546,"sourceCodeEnd":582,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/config/src/main/java/com/alibaba/nacos/config/server/controller/v3/ConfigControllerV3.java#L546-L582","documentation":"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.","triggerScenarios":"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.","commonSituations":"Auto-generating grayName from a path or label containing slashes/spaces; copy-paste introducing hidden characters; using uppercase-only or reserved words.","solutions":["Use only alphanumeric, dash, underscore, colon, and dot characters in grayName.","Trim whitespace before submitting.","Generate grayName from a safe slug function rather than raw user input."],"exampleFix":"// before\ngrayName = \"gray rule #1 / prod\"\n// after\ngrayName = \"gray-rule-1-prod\"","handlingStrategy":"validation","validationCode":"// Validate grayName matches allowed pattern before API call\nprivate static final Pattern GRAY_NAME = Pattern.compile(\"[a-zA-Z0-9-_:\\\\.]+\");\nif (!GRAY_NAME.matcher(grayName.trim()).matches()) {\n    throw new IllegalArgumentException(\"invalid grayName: \" + grayName);\n}","typeGuard":null,"tryCatchPattern":"try { configApi.queryGray(form, grayName); }\ncatch (NacosApiException e) {\n    if (e.getErrCode() == ErrorCode.PARAMETER_VALIDATE_ERROR.getCode())\n        { /* sanitize grayName */ } else throw e;\n}","preventionTips":["Restrict grayName to [a-zA-Z0-9-_:\\.].","Slugify any user-generated grayName before submission."],"tags":["config","gray-release","parameter-validation","validation"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}