alibaba/nacos · error · IllegalArgumentException

AgentVersionContent must contain one JSON value

Error message

AgentVersionContent must contain one JSON value

What it means

Thrown by validateSingleJsonValue when the byte array contains more than one top-level JSON value (e.g. two concatenated JSON objects). Persisted content must be exactly one JSON value to prevent ambiguity in digest and storage.

Source

Thrown at ai/src/main/java/com/alibaba/nacos/ai/service/agent/storage/AgentVersionContentSerializer.java:278

                continue;
            }
            for (Object endpoint : (List<?>) endpoints) {
                if (endpoint instanceof Map) {
                    rejectUnknownFields((Map<?, ?>) endpoint, ENDPOINT_FIELDS,
                        "DeclaredEndpoint");
                }
            }
        }
    }
    
    private static void validateSingleJsonValue(byte[] bytes) {
        try (JsonParser parser = STRICT_JSON_FACTORY.createParser(bytes)) {
            if (parser.nextToken() == null) {
                throw new IllegalArgumentException("AgentVersionContent JSON must not be empty");
            }
            parser.skipChildren();
            if (parser.nextToken() != null) {
                throw new IllegalArgumentException(
                    "AgentVersionContent must contain one JSON value");
            }
        } catch (IOException e) {
            throw new IllegalArgumentException("Invalid AgentVersionContent", e);
        }
    }
    
    private static void rejectUnknownFields(Map<?, ?> value, Set<String> fields,
        String objectName) {
        for (Object field : value.keySet()) {
            if (!fields.contains(field)) {
                throw new IllegalArgumentException("Unknown " + objectName + " field: " + field);
            }
        }
    }
    
    /**
     * Immutable persisted bytes, digest and byte count for one Agent Version content object.

View on GitHub (pinned to 9b989acdf1)

Solutions

  1. Ensure exactly one JSON value is written per storage key.
  2. Re-publish the version to overwrite the concatenated bytes with a single canonical document.
  3. Audit the storage provider for write atomicity.
Defensive patterns

Strategy: try-catch

Try / catch

try {
    return AgentVersionContentSerializer.deserialize(bytes);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("one JSON value")) {
        throw corruptedContent("multiple JSON values in one content cell", e);
    }
    throw e;
}

Prevention

When it happens

Trigger: Deserializing bytes like '{...}{...}' or '{...}123'. After skipping the first value's children, nextToken() is non-null, indicating trailing content.

Common situations: Two JSON documents were concatenated into one storage cell, or a buffering bug appended partial writes. The strict duplicate-detection factory also helps catch structural issues.

Related errors

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