{"record":{"id":"275fc40b9484b65c","repo":"alibaba/nacos","slug":"agentresourceext-schemaversion-must-be-1","errorCode":null,"errorMessage":"AgentResourceExt schemaVersion must be 1","messagePattern":"AgentResourceExt schemaVersion must be 1","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"ai/src/main/java/com/alibaba/nacos/ai/service/agent/metadata/AgentResourceExtSerializer.java","lineNumber":122,"sourceCode":"        } catch (NacosDeserializationException e) {\n            throw new IllegalArgumentException(\"Invalid AgentResourceExt\", e);\n        }\n        validate(result);\n        return result;\n    }\n    \n    /**\n     * Validate Agent resource extension data against schema version 1.\n     *\n     * @param resourceExt typed extension object\n     */\n    public static void validate(AgentResourceExt resourceExt) {\n        if (resourceExt == null) {\n            throw new IllegalArgumentException(\"AgentResourceExt must not be null\");\n        }\n        if (!Integer.valueOf(AgentResourceExt.SCHEMA_VERSION)\n            .equals(resourceExt.getSchemaVersion())) {\n            throw new IllegalArgumentException(\"AgentResourceExt schemaVersion must be \"\n                + AgentResourceExt.SCHEMA_VERSION);\n        }\n        validateOptionalCodePointLength(resourceExt.getDisplayName(),\n            MAX_DISPLAY_NAME_LENGTH, \"displayName\");\n        validateOptionalAbsoluteUri(resourceExt.getIconUrl(), \"iconUrl\");\n        validateProvider(resourceExt.getProvider());\n        validateExtensions(resourceExt.getExtensions());\n        validateCatalog(resourceExt.getVersionCatalog());\n    }\n    \n    private static void validateProvider(AgentProvider provider) {\n        if (provider == null) {\n            return;\n        }\n        validateRequiredCodePointLength(provider.getName(), MAX_PROVIDER_NAME_LENGTH,\n            \"provider.name\");\n        validateOptionalAbsoluteUri(provider.getUrl(), \"provider.url\");\n    }","sourceCodeStart":104,"sourceCodeEnd":140,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/ai/src/main/java/com/alibaba/nacos/ai/service/agent/metadata/AgentResourceExtSerializer.java#L104-L140","documentation":"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.","triggerScenarios":"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.","commonSituations":"Client SDK version newer than server (sends schemaVersion 2), hand-authored JSON missing schemaVersion, or a builder that sets every field except schemaVersion.","solutions":["Set schemaVersion to AgentResourceExt.SCHEMA_VERSION (1) when constructing the object: resourceExt.setSchemaVersion(AgentResourceExt.SCHEMA_VERSION).","For raw JSON, ensure the top-level \"schemaVersion\": 1 key is present and is an integer.","If you genuinely need a newer schema, upgrade the server first; do not send a schemaVersion the running server rejects."],"exampleFix":"// before\nAgentResourceExt ext = new AgentResourceExt();\next.setVersionCatalog(catalog);\nAgentResourceExtSerializer.serialize(ext); // schemaVersion null -> throws\n\n// after\nAgentResourceExt ext = new AgentResourceExt();\next.setSchemaVersion(AgentResourceExt.SCHEMA_VERSION);\next.setVersionCatalog(catalog);\nAgentResourceExtSerializer.serialize(ext);","handlingStrategy":"validation","validationCode":"if (resourceExt.getSchemaVersion() == null\n        || resourceExt.getSchemaVersion() != AgentResourceExt.SCHEMA_VERSION) {\n    throw new AgentExtSchemaVersionException(\"expected \" + AgentResourceExt.SCHEMA_VERSION);\n}\nresourceExt.setSchemaVersion(AgentResourceExt.SCHEMA_VERSION); // normalize before serialize","typeGuard":"static boolean isSupportedSchemaVersion(AgentResourceExt ext) {\n    return ext != null\n        && Integer.valueOf(AgentResourceExt.SCHEMA_VERSION).equals(ext.getSchemaVersion());\n}","tryCatchPattern":"try {\n    AgentResourceExtSerializer.serialize(resourceExt);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage() != null && e.getMessage().startsWith(\"AgentResourceExt schemaVersion must be\")) {\n        throw new UnsupportedSchemaVersionException(e.getMessage());\n    }\n    throw e;\n}","preventionTips":["Always set schemaVersion from the AgentResourceExt.SCHEMA_VERSION constant, never a hardcoded literal.","Gate new schema versions behind a server capability check before sending.","For raw JSON, assert the top-level schemaVersion integer equals 1 before submitting."],"tags":["ai-registry","agent","schema-version","compatibility"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}