alibaba/nacos · error · IllegalArgumentException

Invalid namespaceId: {namespaceId}

Error message

Invalid namespaceId: {namespaceId}

What it means

Thrown by AgentValidationUtils.validateNamespaceId when the namespace identifier is null, longer than MAX_NAMESPACE_LENGTH (128 characters), or does not fully match the pattern [A-Za-z0-9_-]+. Namespace IDs are the tenant/scope identifier used across the Agent (and RAD) APIs and must be a compact token of letters, digits, underscore, and hyphen only — no slashes, spaces, dots, colons, or unicode. This is the single source of truth reused by both AgentValidationUtils and EndpointNaturalKey.

Source

Thrown at api/src/main/java/com/alibaba/nacos/api/ai/utils/AgentValidationUtils.java:76

    private static final Pattern CONTENT_DIGEST_PATTERN = Pattern.compile("sha256:[0-9a-f]{64}");
    
    private static final Pattern MEDIA_TYPE_PATTERN = Pattern.compile("[!-~]+/[!-~]+");
    
    private static final String INTERNAL_ENDPOINT_METADATA_PREFIX = "__nacos.agent.endpoint.";
    
    private AgentValidationUtils() {
    }
    
    /**
     * Validate a namespace identifier.
     *
     * @param namespaceId namespace identifier
     * @throws IllegalArgumentException when invalid
     */
    public static void validateNamespaceId(String namespaceId) {
        if (namespaceId == null || namespaceId.length() > MAX_NAMESPACE_LENGTH
            || !NAMESPACE_PATTERN.matcher(namespaceId).matches()) {
            throw new IllegalArgumentException("Invalid namespaceId: " + namespaceId);
        }
    }
    
    /**
     * Validate an Agent name without rewriting it.
     *
     * @param agentName Agent name
     * @throws IllegalArgumentException when invalid
     */
    public static void validateAgentName(String agentName) {
        if (agentName == null || agentName.isEmpty()
            || agentName.length() > MAX_AGENT_NAME_LENGTH) {
            throw new IllegalArgumentException("Invalid agentName: " + agentName);
        }
        boolean containsNonSpace = false;
        for (int i = 0; i < agentName.length(); i++) {
            char current = agentName.charAt(i);
            if (current < 0x20 || current > 0x7E) {

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Use a compact token matching [A-Za-z0-9_-]+ and <= 128 chars (e.g. 'prod', 'team_foo', 'us-east-1').
2. Use the reserved 'public' namespace when you intend the default/shared scope.
3. Strip/replace illegal characters: spaces -> '-', drop slashes/colons/dots.
4. Validate with AgentValidationUtils.validateNamespaceId(id) before any Agent API call.

Example fix

// before
agent.setNamespaceId("my team/prod"); // space + slash -> rejected
agent.setNamespaceId("");             // empty -> rejected
// after
agent.setNamespaceId("my-team-prod");
// or default scope:
agent.setNamespaceId("public");

import com.alibaba.nacos.api.ai.utils.AgentValidationUtils;
AgentValidationUtils.validateNamespaceId(namespaceId); // throws 'Invalid namespaceId: ...'

import java.util.regex.Pattern;
private static final Pattern NS = Pattern.compile("[A-Za-z0-9_-]+");
static boolean validNamespaceId(String id) {
    return id != null && id.length() <= 128 && NS.matcher(id).matches();
}

try {
    AgentValidationUtils.validateNamespaceId(namespaceId);
} catch (IllegalArgumentException e) {
    // sanitize: replace illegal chars, then retry, or fall back to "public"
}

When it happens

Trigger: Any Agent API call (publish/update/query) or runtime snapshot push whose namespaceId is null/empty/too-long/contains-illegal-chars. Also reached indirectly via EndpointNaturalKey.of which calls validateNamespaceId. Common bad values: 'public' is fine, but 'my ns', 'ns/sub', 'ns:dev', '', or a CJK namespace all fail (empty fails because the + quantifier requires at least one char).

Common situations: Using a human-readable namespace label with spaces instead of the machine ID; including a path separator thinking namespaces are hierarchical; an empty string from a form field; a default-namespace placeholder that slipped through; unicode team names.

Related errors

• 20002
• 10000
• 20002
• 10000
• 20002

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