{"record":{"id":"d924d0306c71961c","repo":"alibaba/nacos","slug":"agent-version-storage-schemaversion-must-be-schem","errorCode":null,"errorMessage":"Agent Version storage schemaVersion must be {SCHEMA_VERSION}","messagePattern":"Agent Version storage schemaVersion must be (.+?)","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"ai/src/main/java/com/alibaba/nacos/ai/service/agent/storage/AgentVersionStorageDescriptorSerializer.java","lineNumber":173,"sourceCode":"        }\n        String provider = descriptor.getProvider();\n        if (provider == null || provider.length() > MAX_PROVIDER_LENGTH\n            || !PROVIDER_PATTERN.matcher(provider).matches()) {\n            throw new IllegalArgumentException(\"Invalid Agent Version storage provider\");\n        }\n        validateRequiredText(\"key\", descriptor.getKey(), MAX_KEY_LENGTH);\n        validateOptionalText(\"keyFormat\", descriptor.getKeyFormat(), MAX_FORMAT_LENGTH);\n        validateOptionalText(\"agentNameCodec\", descriptor.getAgentNameCodec(), MAX_FORMAT_LENGTH);\n        if (descriptor.getContentDigest() == null\n            || !DIGEST_PATTERN.matcher(descriptor.getContentDigest()).matches()) {\n            throw new IllegalArgumentException(\"Invalid Agent Version contentDigest\");\n        }\n        if (!AGENT_VERSION_MEDIA_TYPE.equals(descriptor.getMediaType())) {\n            throw new IllegalArgumentException(\"Agent Version mediaType must be \"\n                + AGENT_VERSION_MEDIA_TYPE);\n        }\n        if (!Integer.valueOf(SCHEMA_VERSION).equals(descriptor.getSchemaVersion())) {\n            throw new IllegalArgumentException(\"Agent Version storage schemaVersion must be \"\n                + SCHEMA_VERSION);\n        }\n        Long size = descriptor.getSize();\n        if (size == null || size < 0 || size > MAX_CONTENT_SIZE) {\n            throw new IllegalArgumentException(\n                \"Agent Version storage size must be between 0 and \" + MAX_CONTENT_SIZE);\n        }\n        if (NACOS_CONFIG_PROVIDER.equals(provider)) {\n            if (!NACOS_CONFIG_KEY_FORMAT.equals(descriptor.getKeyFormat())) {\n                throw new IllegalArgumentException(\"nacos_config keyFormat must be \"\n                    + NACOS_CONFIG_KEY_FORMAT);\n            }\n            if (!RAD_ASCII_AGENT_NAME_CODEC.equals(descriptor.getAgentNameCodec())) {\n                throw new IllegalArgumentException(\"nacos_config agentNameCodec must be \"\n                    + RAD_ASCII_AGENT_NAME_CODEC);\n            }\n        }\n    }","sourceCodeStart":155,"sourceCodeEnd":191,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/ai/src/main/java/com/alibaba/nacos/ai/service/agent/storage/AgentVersionStorageDescriptorSerializer.java#L155-L191","documentation":"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.","triggerScenarios":"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.","commonSituations":"Reading a row from a newer or older Nacos version with a different schema; a manual edit; code using a hardcoded wrong number.","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"],"exampleFix":"// before\ndescriptor.setSchemaVersion(2);\n// after\ndescriptor.setSchemaVersion(AgentVersionStorageDescriptor.SCHEMA_VERSION);","handlingStrategy":"validation","validationCode":"if (!Integer.valueOf(AgentVersionStorageDescriptor.SCHEMA_VERSION)\n        .equals(descriptor.getSchemaVersion())) {\n    descriptor.setSchemaVersion(AgentVersionStorageDescriptor.SCHEMA_VERSION);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Reference the SCHEMA_VERSION constant, never a hardcoded number","Run the schema migration when upgrading to a Nacos version that bumps SCHEMA_VERSION"],"tags":["java","nacos","ai-agent","validation","schema-version","storage-descriptor","versioning"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}