alibaba/nacos · error · NacosApiException

10000

10000

Error message

Request parameter `agentSpecName` should not be blank.

What it means

Thrown by AgentValidationUtils.validateEndpointMetadata when a metadata key is null, empty, longer than 64 code points (MAX_METADATA_KEY_LENGTH), or reserved. Reserved keys are 'preserved.heart.beat.interval', 'preserved.heart.beat.timeout', 'preserved.ip.delete.timeout', and any key starting with '__nacos.agent.endpoint.'.

Source

Thrown at ai/src/main/java/com/alibaba/nacos/ai/form/agentspecs/admin/AgentSpecBizTagsUpdateForm.java:45

 * AgentSpec biz tags update form.
 *
 * @author nacos
 */
public class AgentSpecBizTagsUpdateForm extends AgentSpecForm {
    
    @Serial
    private static final long serialVersionUID = 1L;
    
    /**
     * JSON string: ["tag1","tag2"].
     */
    private String bizTags;
    
    @Override
    public void validate() throws NacosApiException {
        fillDefaultNamespaceId();
        if (StringUtils.isBlank(getAgentSpecName())) {
            throw new NacosApiException(NacosException.INVALID_PARAM, ErrorCode.PARAMETER_MISSING,
                "Request parameter `agentSpecName` should not be blank.");
        }
    }
    
    public String getBizTags() {
        return bizTags;
    }
    
    public void setBizTags(String bizTags) {
        this.bizTags = bizTags;
    }
}

View on GitHub (pinned to 9b989acdf1)

Solutions

Avoid the reserved 'preserved.heart.beat.*', 'preserved.ip.delete.timeout', and '__nacos.agent.endpoint.*' keys.
Ensure every key is non-empty and <=64 code points.
Namespace your own keys with a stable prefix (e.g. 'app.region') to avoid collisions.

Example fix

// before
meta.put("preserved.heart.beat.interval", "5000");
// after
meta.put("app.heartbeat.interval", "5000");

Defensive patterns

Strategy: validation

Validate before calling

for (Map.Entry<String,String> e : metadata.entrySet()) {
    String k = e.getKey();
    if (k == null || k.isEmpty() || k.codePointCount(0, k.length()) > 64
            || "preserved.heart.beat.interval".equals(k)
            || "preserved.heart.beat.timeout".equals(k)
            || "preserved.ip.delete.timeout".equals(k)
            || k.startsWith("__nacos.agent.endpoint.")) {
        throw new IllegalArgumentException("Invalid Endpoint metadata key: " + k);
    }
}

Type guard

static boolean isValidMetadataKey(String k) {
    return k != null && !k.isEmpty() && k.codePointCount(0, k.length()) <= 64
        && !"preserved.heart.beat.interval".equals(k)
        && !"preserved.heart.beat.timeout".equals(k)
        && !"preserved.ip.delete.timeout".equals(k)
        && !k.startsWith("__nacos.agent.endpoint.");
}

Try / catch

try {
    AgentValidationUtils.validateEndpointMetadata(metadata);
} catch (IllegalArgumentException e) {
    // return 400, invalid metadata key
}

Prevention

Avoid 'preserved.*' and '__nacos.agent.endpoint.*' keys.
Namespace your own keys with a stable prefix.

When it happens

Trigger: Putting a reserved key (e.g. 'preserved.heart.beat.interval') into Endpoint metadata, or a key that is null/empty/>64 code points, during canonicalization (EndpointCanonicalizer line 77), runtime endpoint mapping, or resolve filter metadataSelector.

Common situations: Reusing Nacos naming 'preserved.*' metadata keys inside AI Endpoint metadata (they are naming-instance internals, not allowed here); a merge producing a null key; very long auto-generated keys.

Related errors

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