alibaba/nacos · error · IllegalArgumentException

Invalid Endpoint metadata value for key: {key}

Error message

Invalid Endpoint metadata value for key: {key}

What it means

Error "Invalid Endpoint metadata value for key: {key}" thrown in alibaba/nacos.

Source

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

     * @throws IllegalArgumentException when invalid or using a reserved key
     */
    public static void validateEndpointMetadata(Map<String, String> metadata) {
        if (metadata == null) {
            return;
        }
        if (metadata.size() > MAX_METADATA_SIZE) {
            throw new IllegalArgumentException(
                "Endpoint metadata exceeds " + MAX_METADATA_SIZE + " entries");
        }
        for (Map.Entry<String, String> entry : metadata.entrySet()) {
            String key = entry.getKey();
            String value = entry.getValue();
            if (key == null || key.isEmpty() || codePointLength(key) > MAX_METADATA_KEY_LENGTH
                || isReservedMetadataKey(key)) {
                throw new IllegalArgumentException("Invalid Endpoint metadata key: " + key);
            }
            if (value == null || codePointLength(value) > MAX_METADATA_VALUE_LENGTH) {
                throw new IllegalArgumentException(
                    "Invalid Endpoint metadata value for key: " + key);
            }
        }
    }
    
    private static boolean isReservedMetadataKey(String key) {
        return "preserved.heart.beat.interval".equals(key)
            || "preserved.heart.beat.timeout".equals(key)
            || "preserved.ip.delete.timeout".equals(key)
            || key.startsWith(INTERNAL_ENDPOINT_METADATA_PREFIX);
    }
    
    private static int codePointLength(String value) {
        return value.codePointCount(0, value.length());
    }
    
    private static void validatePrintableAscii(String value, String fieldName) {
        for (int i = 0; i < value.length(); i++) {

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Correct the invalid value for endpoint metadata value to match the expected format or allowed set, then retry.

When it happens

Trigger: Thrown at api/src/main/java/com/alibaba/nacos/api/ai/utils/AgentValidationUtils.java:252 when the library encounters an invalid state.

Common situations: Endpoint metadata uses a value that fails the value syntax rules.

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