alibaba/nacos · error · NacosApiException

10000

10000

Error message

Required parameter 'grayRuleExp' type String is not present

What it means

Thrown by validateGrayForm during POST /v3/admin/cs/config/gray when grayRuleExp is blank. The gray rule expression defines which client labels trigger the gray config; without it the gray is meaningless. Returns HTTP 400 code 10000 (PARAMETER_MISSING). For tag gray rules the expression must be in key=value(s) format.

Source

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

    @Since("3.2.2")
    @DeleteMapping("/gray")
    @Secured(action = ActionTypes.WRITE, signType = SignType.CONFIG, apiType = ApiType.ADMIN_API)
    public Result<Boolean> stopGray(HttpServletRequest request, ConfigFormV3 configForm,
        @RequestParam("grayName") String grayName) throws NacosApiException {
        configForm.validate();
        validateGrayName(grayName);
        String namespaceId = NamespaceUtil.processNamespaceParameter(configForm.getNamespaceId());
        String clientIp = getRemoteIp(request);
        String srcUser = RequestUtil.getSrcUserName(request);
        return Result.success(
            configOperationService.deleteConfig(configForm.getDataId(), configForm.getGroupName(),
                namespaceId, grayName, clientIp, srcUser, Constants.HTTP));
    }
    
    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);
        }

View on GitHub (pinned to 9b989acdf1)

Solutions

Provide a non-blank grayRuleExp in the ConfigFormV3, e.g. 'zone=us-east-1' for a single-tag rule.
When using the grayMatchRuleExp request param on POST /gray, ensure it is set and non-empty so it is copied into grayRuleExp.
Match the rule format to the grayType (TAG_V2 uses key=value1,value2; multi-tag supports && and ||).

Example fix

// before
POST /v3/admin/cs/config/gray  { "dataId":"app", "groupName":"G", "grayName":"r1", "grayVersion":"v1" }
// after
POST /v3/admin/cs/config/gray  { "dataId":"app", "groupName":"G", "grayName":"r1", "grayVersion":"v1", "grayRuleExp":"zone=us-east-1" }

Defensive patterns

Strategy: validation

Validate before calling

if (StringUtils.isBlank(configForm.getGrayRuleExp())
    && StringUtils.isBlank(grayMatchRuleExp)) {
    // reject before API call — supply grayRuleExp
    throw new IllegalArgumentException("grayRuleExp is required for gray publish");
}

Try / catch

try { configApi.publishGray(form); }
catch (NacosApiException e) {
    if (e.getErrCode() == ErrorCode.PARAMETER_MISSING.getCode())
        { /* supply grayRuleExp */ } else throw e;
}

Prevention

Always include grayRuleExp when publishing a gray config.
For TAG_V2 grayType, use key=value format.

When it happens

Trigger: POSTing a gray config without the grayRuleExp field (or grayMatchRuleExp request param), or passing an empty string. Also when grayType is TAG_V2 but no rule expression is supplied.

Common situations: First-time gray publish where the developer forgets the rule expression; API client sends grayRuleExp=null; confusion between grayRuleExp and grayMatchRuleExp query params (publishGray uses grayMatchRuleExp which is copied into grayRuleExp).

Related errors

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