alibaba/nacos · error · IllegalArgumentException

Agent Version storage schemaVersion must be {SCHEMA_VERSION}

Error message

Agent Version storage schemaVersion must be {SCHEMA_VERSION}

What it means

The schemaVersion field must equal exactly 1 (AgentVersionStorageDescriptor.SCHEMA_VERSION). This integer versions the storage layout so the serializer can reject rows written by an incompatible schema and force an explicit migration.

Source

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

        }
        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())) {
            throw new IllegalArgumentException("Agent Version storage schemaVersion must be "
                + SCHEMA_VERSION);
        }
        Long size = descriptor.getSize();
        if (size == null || size < 0 || size > MAX_CONTENT_SIZE) {
            throw new IllegalArgumentException(
                "Agent Version storage size must be between 0 and " + MAX_CONTENT_SIZE);
        }
        if (NACOS_CONFIG_PROVIDER.equals(provider)) {
            if (!NACOS_CONFIG_KEY_FORMAT.equals(descriptor.getKeyFormat())) {
                throw new IllegalArgumentException("nacos_config keyFormat must be "
                    + NACOS_CONFIG_KEY_FORMAT);
            }
            if (!RAD_ASCII_AGENT_NAME_CODEC.equals(descriptor.getAgentNameCodec())) {
                throw new IllegalArgumentException("nacos_config agentNameCodec must be "
                    + RAD_ASCII_AGENT_NAME_CODEC);
            }
        }
    }

View on GitHub (pinned to 9b989acdf1)

Solutions

Set schemaVersion to AgentVersionStorageDescriptor.SCHEMA_VERSION (1)
Run the appropriate schema migration when upgrading across versions that change SCHEMA_VERSION
Re-publish the version so the current server writes the correct schema version

Example fix

// before
descriptor.setSchemaVersion(2);
// after
descriptor.setSchemaVersion(AgentVersionStorageDescriptor.SCHEMA_VERSION);

Defensive patterns

Strategy: validation

Validate before calling

if (!Integer.valueOf(AgentVersionStorageDescriptor.SCHEMA_VERSION)
        .equals(descriptor.getSchemaVersion())) {
    descriptor.setSchemaVersion(AgentVersionStorageDescriptor.SCHEMA_VERSION);
}

Prevention

Reference the SCHEMA_VERSION constant, never a hardcoded number
Run the schema migration when upgrading to a Nacos version that bumps SCHEMA_VERSION

When it happens

Trigger: validate()/serialize() on a descriptor whose schemaVersion is null, 0, 2, or any value other than 1. Also fires when reading a row written by a different Nacos schema version.

Common situations: Reading a row from a newer or older Nacos version with a different schema; a manual edit; code using a hardcoded wrong number.

Related errors

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