alibaba/nacos · error · NacosApiException

10000

10000

Error message

Request parameter `agentSpecCard` should not be `null` or empty.

What it means

Thrown by AgentValidationUtils.validateEndpointMetadata when a metadata value is null or longer than 256 code points (MAX_METADATA_VALUE_LENGTH). The check uses codePointCount, so supplementary-plane characters (emoji etc.) count as one code point but multi-byte. Keys are validated first, so the offending key is named in the message.

Source

Thrown at ai/src/main/java/com/alibaba/nacos/ai/form/agentspecs/admin/AgentSpecDetailForm.java:47

 * @author nacos
 */
public class AgentSpecDetailForm extends AgentSpecForm {
    
    @Serial
    private static final long serialVersionUID = 1L;
    
    /**
     * AgentSpec card JSON string, contains complete AgentSpec information.
     */
    private String agentSpecCard;
    
    @Override
    public void validate() throws NacosApiException {
        fillDefaultNamespaceId();
        // For create/detail, agentSpecName is optional (can be in agentSpecCard)
        // Only agentSpecCard is required
        if (StringUtils.isEmpty(agentSpecCard)) {
            throw new NacosApiException(NacosException.INVALID_PARAM, ErrorCode.PARAMETER_MISSING,
                "Request parameter `agentSpecCard` should not be `null` or empty.");
        }
    }
    
    public String getAgentSpecCard() {
        return agentSpecCard;
    }
    
    public void setAgentSpecCard(String agentSpecCard) {
        this.agentSpecCard = agentSpecCard;
    }
}

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Keep each metadata value non-null and <=256 code points.
2. Move large payloads (certificates, descriptors) out of metadata into a referenced resource.
3. Sanitize map merges to drop null values before submission.

Example fix

// before
meta.put("app.config", hugeJsonBlob); // 600 chars
// after
meta.put("app.configRef", descriptorUri);

for (Map.Entry<String,String> e : metadata.entrySet()) {
    String v = e.getValue();
    if (v == null || v.codePointCount(0, v.length()) > 256) {
        throw new IllegalArgumentException("Invalid Endpoint metadata value for key: " + e.getKey());
    }
}

static boolean isValidMetadataValue(String v) {
    return v != null && v.codePointCount(0, v.length()) <= 256;
}

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

When it happens

Trigger: Putting a null value or a value longer than 256 code points into Endpoint metadata during canonicalization/runtime mapping. For example embedding a long JSON blob or URL as a metadata value.

Common situations: Storing a serialized object, base64 payload, or full URL+token as a metadata value; null values from a map merge where one side lacked the key; emoji-rich values inflating perceived length.

Related errors

• 20002
• 20002
• 10000
• 10000
• endpointSourceOrder must contain 1 or 2 sources

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