alibaba/nacos · error · NacosApiException

20002

20002

Error message

Request parameter `endpointSource` contains an invalid value.

What it means

Thrown by AgentValidationUtils.validateNonNullJsonValue when a required JSON-compatible field deserialized to Java null. After request binding, a JSON null (explicit null) and an absent field both yield a Java null reference; this guard rejects it for fields the schema marks required. The dynamic fieldName names the offending property.

Source

Thrown at ai/src/main/java/com/alibaba/nacos/ai/form/agent/client/AgentDiscoveryForm.java:121

        result.setProtocolVersion(protocolVersion);
        result.setTransports(transport);
        result.setEndpointSources(parseEndpointSources());
        result.setMetadataSelector(selector);
        return result;
    }
    
    private List<EndpointSource> parseEndpointSources() throws NacosApiException {
        if (endpointSource == null) {
            return null;
        }
        List<EndpointSource> result = new ArrayList<EndpointSource>(endpointSource.size());
        try {
            for (String source : endpointSource) {
                result.add(EndpointSource.valueOf(source));
            }
            return result;
        } catch (IllegalArgumentException | NullPointerException e) {
            throw new NacosApiException(NacosException.INVALID_PARAM,
                ErrorCode.PARAMETER_VALIDATE_ERROR,
                "Request parameter `endpointSource` contains an invalid value.");
        }
    }
    
    public String getNamespaceId() {
        return namespaceId;
    }
    
    public void setNamespaceId(String namespaceId) {
        this.namespaceId = namespaceId;
    }
    
    public String getAgentName() {
        return agentName;
    }
    
    public void setAgentName(String agentName) {

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Provide a concrete JSON value for the required field (object, array, or scalar) instead of null.
2. Make your client schema explicit so required fields are always populated.
3. If the field is genuinely optional on your side, do not route it through validateNonNullJsonValue.

Example fix

// before
{ "nativeDescriptor": null }
// after
{ "nativeDescriptor": { "openrpc": "1.2.0" } }

if (value == null) {
    throw new IllegalArgumentException(fieldName + " must not be JSON null");
}

static boolean isPresentJsonValue(Object v) {
    return v != null;
}

try {
    AgentValidationUtils.validateNonNullJsonValue(value, fieldName);
} catch (IllegalArgumentException e) {
    // return 400, required field missing
}

When it happens

Trigger: Submitting a call interface (RadModelValidator.validateCallInterface line 343) whose nativeDescriptor is JSON null or absent. Any caller using validateNonNullJsonValue on a required object field hits this when the client sends null.

Common situations: Distinguishing 'unset' from 'null' in JSON — a client sending {"nativeDescriptor": null} or omitting the key both deserialize to null; schema drift where a field became required but clients still omit it.

Related errors

• 20002
• 10000
• 20002
• 10000
• 20002

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