alibaba/nacos · warning · NacosApiException

22000

22000

Error message

namespaceId [{namespaceId}] mismatch the pattern

What it means

Thrown on namespace creation (POST) when a user-supplied namespaceId does not match the allowed pattern ^[\\w-]+ (word characters [A-Za-z0-9_] and hyphens). NacosApiException ErrorCode.ILLEGAL_NAMESPACE (code 22000), HTTP 400. Note: the pattern is applied after a trim().

Source

Thrown at core/src/main/java/com/alibaba/nacos/core/controller/v3/NamespaceControllerV3.java:130

    @Since("3.0.0")
    @PostMapping
    @Secured(resource = Commons.NACOS_ADMIN_CORE_CONTEXT_V3
        + "namespaces", action = ActionTypes.WRITE, signType = SignType.CONSOLE,
        apiType = ApiType.ADMIN_API)
    public Result<Boolean> createNamespace(NamespaceForm namespaceForm) throws Exception {
        namespaceForm.validate();
        
        String namespaceId = namespaceForm.getNamespaceId();
        String namespaceName = namespaceForm.getNamespaceName();
        String namespaceDesc = namespaceForm.getNamespaceDesc();
        
        if (StringUtils.isBlank(namespaceId)) {
            namespaceId = UUID.randomUUID().toString();
        } else {
            // TODO check should be parameter check filter.
            namespaceId = namespaceId.trim();
            if (!namespaceIdCheckPattern.matcher(namespaceId).matches()) {
                throw new NacosApiException(HttpStatus.BAD_REQUEST.value(),
                    ErrorCode.ILLEGAL_NAMESPACE,
                    "namespaceId [" + namespaceId + "] mismatch the pattern");
            }
            if (namespaceId.length() > NAMESPACE_ID_MAX_LENGTH) {
                throw new NacosApiException(HttpStatus.BAD_REQUEST.value(),
                    ErrorCode.ILLEGAL_NAMESPACE,
                    "too long namespaceId, over " + NAMESPACE_ID_MAX_LENGTH);
            }
        }
        // contains illegal chars
        if (!namespaceNameCheckPattern.matcher(namespaceName).matches()) {
            throw new NacosApiException(HttpStatus.BAD_REQUEST.value(), ErrorCode.ILLEGAL_NAMESPACE,
                "namespaceName [" + namespaceName + "] contains illegal char");
        }
        return Result.success(
            namespaceOperationService.createNamespace(namespaceId, namespaceName, namespaceDesc));
    }
    

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Restrict namespaceId to letters, digits, underscore, and hyphen only (e.g. 'dev-env', 'tenant_1').
2. Omit the namespaceId entirely to let Nacos generate a UUID.
3. If you need dots/colons, that is intentionally disallowed — redesign the id scheme.

Example fix

// before
POST /v3/admin/core/namespace
{"customNamespaceId":"dev.env"}

// after
POST /v3/admin/core/namespace
{"customNamespaceId":"dev-env"}

private static final Pattern ID = Pattern.compile("^[\\\\w-]+$");
if (namespaceId != null && !ID.matcher(namespaceId.trim()).matches()) {
    // reject before calling the create API
}

try {
    client.createNamespace(form);
} catch (NacosApiException e) {
    if (e.getErrCode() == ErrorCode.ILLEGAL_NAMESPACE.getCode()) { /* fix the id */ }
}

When it happens

Trigger: Submitting a custom namespaceId containing spaces, dots, slashes, colons, @, or other non-word/non-hyphen characters. The regex is matched with Matcher.matches() which requires the ENTIRE string to conform (anchored by ^, though note the pattern lacks a trailing $ anchor which is a known quirk).

Common situations: Operator wants a 'dev.env' or 'tenant:a' namespace id; copying an id containing dots/colons from another system; trailing/leading characters that the pattern rejects.

Related errors

• 23000
• 10000
• 20002
• 10000
• 20002

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