alibaba/nacos · error · IllegalArgumentException

AgentResourceExt schemaVersion must be 1

Error message

AgentResourceExt schemaVersion must be 1

What it means

validate() requires resourceExt.getSchemaVersion() to equal AgentResourceExt.SCHEMA_VERSION (currently 1), compared via Integer boxing equality. A null schemaVersion, 0, 2, or any other value fails. The version pin is how the serializer enforces forward/backward compatibility of the ext schema.

Source

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

        } catch (NacosDeserializationException e) {
            throw new IllegalArgumentException("Invalid AgentResourceExt", e);
        }
        validate(result);
        return result;
    }
    
    /**
     * Validate Agent resource extension data against schema version 1.
     *
     * @param resourceExt typed extension object
     */
    public static void validate(AgentResourceExt resourceExt) {
        if (resourceExt == null) {
            throw new IllegalArgumentException("AgentResourceExt must not be null");
        }
        if (!Integer.valueOf(AgentResourceExt.SCHEMA_VERSION)
            .equals(resourceExt.getSchemaVersion())) {
            throw new IllegalArgumentException("AgentResourceExt schemaVersion must be "
                + AgentResourceExt.SCHEMA_VERSION);
        }
        validateOptionalCodePointLength(resourceExt.getDisplayName(),
            MAX_DISPLAY_NAME_LENGTH, "displayName");
        validateOptionalAbsoluteUri(resourceExt.getIconUrl(), "iconUrl");
        validateProvider(resourceExt.getProvider());
        validateExtensions(resourceExt.getExtensions());
        validateCatalog(resourceExt.getVersionCatalog());
    }
    
    private static void validateProvider(AgentProvider provider) {
        if (provider == null) {
            return;
        }
        validateRequiredCodePointLength(provider.getName(), MAX_PROVIDER_NAME_LENGTH,
            "provider.name");
        validateOptionalAbsoluteUri(provider.getUrl(), "provider.url");
    }

View on GitHub (pinned to 9b989acdf1)

Solutions

  1. Set schemaVersion to AgentResourceExt.SCHEMA_VERSION (1) when constructing the object: resourceExt.setSchemaVersion(AgentResourceExt.SCHEMA_VERSION).
  2. For raw JSON, ensure the top-level "schemaVersion": 1 key is present and is an integer.
  3. If you genuinely need a newer schema, upgrade the server first; do not send a schemaVersion the running server rejects.

Example fix

// before
AgentResourceExt ext = new AgentResourceExt();
ext.setVersionCatalog(catalog);
AgentResourceExtSerializer.serialize(ext); // schemaVersion null -> throws

// after
AgentResourceExt ext = new AgentResourceExt();
ext.setSchemaVersion(AgentResourceExt.SCHEMA_VERSION);
ext.setVersionCatalog(catalog);
AgentResourceExtSerializer.serialize(ext);
Defensive patterns

Strategy: validation

Validate before calling

if (resourceExt.getSchemaVersion() == null
        || resourceExt.getSchemaVersion() != AgentResourceExt.SCHEMA_VERSION) {
    throw new AgentExtSchemaVersionException("expected " + AgentResourceExt.SCHEMA_VERSION);
}
resourceExt.setSchemaVersion(AgentResourceExt.SCHEMA_VERSION); // normalize before serialize

Type guard

static boolean isSupportedSchemaVersion(AgentResourceExt ext) {
    return ext != null
        && Integer.valueOf(AgentResourceExt.SCHEMA_VERSION).equals(ext.getSchemaVersion());
}

Try / catch

try {
    AgentResourceExtSerializer.serialize(resourceExt);
} catch (IllegalArgumentException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("AgentResourceExt schemaVersion must be")) {
        throw new UnsupportedSchemaVersionException(e.getMessage());
    }
    throw e;
}

Prevention

When it happens

Trigger: Calling serialize() on a programmatically built AgentResourceExt whose schemaVersion was never set (defaults to null), or deserialize() of a payload whose schemaVersion field is missing/0/2. Triggered when an agent is created/updated via the AI admin API with an ext that omits schemaVersion, or when a client targets a newer schema the server does not support.

Common situations: Client SDK version newer than server (sends schemaVersion 2), hand-authored JSON missing schemaVersion, or a builder that sets every field except schemaVersion.

Related errors

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