alibaba/nacos · error · IllegalArgumentException

Agent Version storage descriptor must not be null

Error message

Agent Version storage descriptor must not be null

What it means

Thrown by validate() when the AgentVersionStorageDescriptor object itself is null. It guards serialize(null), validate(null), AgentVersionStorageService.prepare(null, content), and the PreparedAgentVersionWrite constructor before any field is accessed.

Source

Thrown at ai/src/main/java/com/alibaba/nacos/ai/service/agent/storage/AgentVersionStorageDescriptorSerializer.java:154

        validateJsonText(root, "provider", false);
        validateJsonText(root, "key", false);
        validateJsonText(root, "keyFormat", true);
        validateJsonText(root, "agentNameCodec", true);
        validateJsonText(root, "contentDigest", false);
        validateJsonText(root, "mediaType", false);
        validateJsonInteger(root, "schemaVersion");
        validateJsonInteger(root, "size");
    }
    
    /**
     * Validate an Agent Version storage descriptor against the internal storage schema.
     *
     * @param descriptor storage descriptor
     * @throws IllegalArgumentException when the descriptor is invalid
     */
    public static void validate(AgentVersionStorageDescriptor descriptor) {
        if (descriptor == null) {
            throw new IllegalArgumentException("Agent Version storage descriptor must not be null");
        }
        String provider = descriptor.getProvider();
        if (provider == null || provider.length() > MAX_PROVIDER_LENGTH
            || !PROVIDER_PATTERN.matcher(provider).matches()) {
            throw new IllegalArgumentException("Invalid Agent Version storage provider");
        }
        validateRequiredText("key", descriptor.getKey(), MAX_KEY_LENGTH);
        validateOptionalText("keyFormat", descriptor.getKeyFormat(), MAX_FORMAT_LENGTH);
        validateOptionalText("agentNameCodec", descriptor.getAgentNameCodec(), MAX_FORMAT_LENGTH);
        if (descriptor.getContentDigest() == null
            || !DIGEST_PATTERN.matcher(descriptor.getContentDigest()).matches()) {
            throw new IllegalArgumentException("Invalid Agent Version contentDigest");
        }
        if (!AGENT_VERSION_MEDIA_TYPE.equals(descriptor.getMediaType())) {
            throw new IllegalArgumentException("Agent Version mediaType must be "
                + AGENT_VERSION_MEDIA_TYPE);
        }
        if (!Integer.valueOf(SCHEMA_VERSION).equals(descriptor.getSchemaVersion())) {

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Guarantee the descriptor is constructed before calling serialize/validate
2. Build the descriptor via AgentVersionStorageService.prepare(...) which always returns a non-null descriptor
3. Add an explicit null check and fail fast with a domain-specific NacosException message

Example fix

// before
String storage = AgentVersionStorageDescriptorSerializer.serialize(maybeNullDescriptor);
// after
if (descriptor == null) {
    throw new NacosException(NacosException.SERVER_ERROR, "Agent Version descriptor missing");
}
String storage = AgentVersionStorageDescriptorSerializer.serialize(descriptor);

if (descriptor == null) {
    throw new NacosException(NacosException.SERVER_ERROR,
        "Agent Version descriptor must not be null");
}
AgentVersionStorageDescriptorSerializer.serialize(descriptor);

private static boolean isValidDescriptor(AgentVersionStorageDescriptor d) {
    return d != null;
}

When it happens

Trigger: AgentVersionStorageDescriptorSerializer.serialize(null), validate(null), or AgentVersionStorageService.prepare(null, content). Reached when a code path conditionally builds a descriptor and passes null through.

Common situations: A draft flow that has no prepared content yet; a conditional builder that returns null on an edge case; a missing null check before persisting.

Related errors

• Agent Version storage descriptor JSON must not be empty
• Agent Version storage descriptor must be a JSON object
• Unknown Agent Version storage descriptor field: {fieldName}
• Invalid Agent Version storage provider
• Invalid Agent Version contentDigest

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