alibaba/nacos · error · NacosApiException

20002

20002

Error message

Request parameter `%s` is not valid JSON.

What it means

Thrown by AgentValidationUtils.validateMediaType when the descriptor media type is null, longer than 128 chars, or fails [!-~]+/[!-~]+ — i.e. printable ASCII (0x21-0x7E) on both sides of a single slash. The message uses the literal token 'descriptorMediaType'. It enforces a 'type/subtype' shape with no spaces and no extra slashes in either part.

Source

Thrown at ai/src/main/java/com/alibaba/nacos/ai/form/agent/client/AgentClientFormJsonParser.java:45

/**
 * JSON-valued form-field parser for the Agent Client API.
 *
 * @author Nacos
 */
final class AgentClientFormJsonParser {
    
    private AgentClientFormJsonParser() {
    }
    
    static <T> T parseOptional(String fieldName, String value,
        NacosTypeReference<T> targetType) throws NacosApiException {
        if (StringUtils.isBlank(value)) {
            return null;
        }
        try {
            return JsonUtils.toObj(value, targetType);
        } catch (NacosDeserializationException e) {
            throw new NacosApiException(NacosException.INVALID_PARAM,
                ErrorCode.PARAMETER_VALIDATE_ERROR,
                "Request parameter `" + fieldName + "` is not valid JSON.");
        }
    }
}

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Send a standard 'type/subtype' pair in printable ASCII without parameters, e.g. 'application/json', 'application/octet-stream'.
2. Drop '; charset=...' and other parameters; they are not part of the descriptor media type here.
3. Null-check before binding when the field is optional.

Example fix

// before
iface.setDescriptorMediaType("application/json; charset=utf-8");
// after
iface.setDescriptorMediaType("application/json");

if (mediaType == null || mediaType.length() > 128
        || !mediaType.matches("^[!-~]+/[!-~]+$")) {
    throw new IllegalArgumentException("Invalid descriptorMediaType");
}

static boolean isValidMediaType(String s) {
    return s != null && s.length() <= 128
        && s.matches("^[!-~]+/[!-~]+$");
}

try {
    AgentValidationUtils.validateMediaType(mediaType);
} catch (IllegalArgumentException e) {
    // return 400, field 'descriptorMediaType'
}

When it happens

Trigger: Setting callInterface.descriptorMediaType via RadModelValidator.validateCallInterface (line 342) to null, a value without a slash ('json'), with spaces ('application / json'), with a non-ASCII char, or >128 chars.

Common situations: Sending a bare format name instead of a full media type; including a charset parameter ('application/json; charset=utf-8') which is not allowed by this token grammar; copy-paste introducing a space around the slash.

Related errors

• 10000
• 10000
• 20002
• 20002
• 10000

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