alibaba/nacos · error · IllegalArgumentException

AgentResourceExt must contain one JSON value

Error message

AgentResourceExt must contain one JSON value

What it means

The ai_resource.ext JSON must contain exactly one top-level JSON value. The validateSingleJsonValue helper (line 409) throws this when trailing content remains after the first complete JSON value is parsed. This catches concatenated JSON like '{}{}' or '{} 123' which would otherwise silently parse only the first value.

Source

Thrown at ai/src/main/java/com/alibaba/nacos/ai/service/agent/metadata/AgentResourceExtSerializer.java:410

    
    private static void rejectUnknownFields(Map<?, ?> object, Set<String> allowedFields,
        String objectName) {
        for (Object field : object.keySet()) {
            if (!allowedFields.contains(field)) {
                throw new IllegalArgumentException(
                    "Unknown " + objectName + " field: " + field);
            }
        }
    }
    
    private static void validateSingleJsonValue(String json) {
        try (JsonParser parser = STRICT_JSON_FACTORY.createParser(json)) {
            if (parser.nextToken() == null) {
                throw new IllegalArgumentException("AgentResourceExt JSON must not be empty");
            }
            parser.skipChildren();
            if (parser.nextToken() != null) {
                throw new IllegalArgumentException(
                    "AgentResourceExt must contain one JSON value");
            }
        } catch (IOException e) {
            throw new IllegalArgumentException("Invalid AgentResourceExt", e);
        }
    }
    
    private static Set<String> unmodifiableSet(String... fields) {
        return Collections.unmodifiableSet(new HashSet<String>(Arrays.asList(fields)));
    }
}

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Ensure the JSON string contains exactly one top-level JSON object with no trailing content.
2. If storing multiple documents, use a JSON array wrapper or separate columns/rows.
3. Trim trailing whitespace and verify with a JSON parser before persistence.

Example fix

// before
'{"schemaVersion":1}{"schemaVersion":2}'
// after
'{"schemaVersion":1}'

// Use Jackson to verify single-value JSON
ObjectMapper mapper = new ObjectMapper();
mapper.readValue(json, Object.class);
// Jackson's readValue with default settings throws on trailing tokens

public static boolean isSingleJsonValue(String json) {
    try (JsonParser p = new JsonFactory().createParser(json)) {
        p.nextToken();
        p.skipChildren();
        return p.nextToken() == null;
    } catch (IOException e) {
        return false;
    }
}

try {
    AgentResourceExtSerializer.deserialize(json);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("one JSON value")) {
        // split the input and process each JSON object separately
    }
    throw e;
}

When it happens

Trigger: Calling AgentResourceExtSerializer.deserialize() on a string like '{...}{...}' or '{...} extra'. Also possible if a file or database column accidentally concatenates two JSON documents.

Common situations: Appending to a JSON file without array-wrapping; database column pollution from a bug that concatenated two writes; log or stream parsing errors that include delimiters.

Related errors

• Missing AgentResourceExt field: versionCatalog
• AgentVersionCatalog onlineVersions must be an array
• {} must be an array
• {} must contain only strings
• {} must be a JSON object

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