{"record":{"id":"2c73e94056609f13","repo":"alibaba/nacos","slug":"unknown-agent-version-storage-descriptor-field-f","errorCode":null,"errorMessage":"Unknown Agent Version storage descriptor field: {fieldName}","messagePattern":"Unknown Agent Version storage descriptor field: (.+?)","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"ai/src/main/java/com/alibaba/nacos/ai/service/agent/storage/AgentVersionStorageDescriptorSerializer.java","lineNumber":132,"sourceCode":"    private static void validateJsonShape(String json) {\n        if (json == null || json.isEmpty()) {\n            throw new IllegalArgumentException(\n                \"Agent Version storage descriptor JSON must not be empty\");\n        }\n        validateSingleJsonValue(json);\n        final Map<?, ?> root;\n        try {\n            root = JacksonUtils.toObj(json, Map.class);\n        } catch (NacosDeserializationException e) {\n            throw new IllegalArgumentException(\"Invalid Agent Version storage descriptor\", e);\n        }\n        if (root == null) {\n            throw new IllegalArgumentException(\n                \"Agent Version storage descriptor must be a JSON object\");\n        }\n        for (Object fieldName : root.keySet()) {\n            if (!FIELDS.contains(fieldName)) {\n                throw new IllegalArgumentException(\n                    \"Unknown Agent Version storage descriptor field: \" + fieldName);\n            }\n        }\n        validateJsonText(root, \"provider\", false);\n        validateJsonText(root, \"key\", false);\n        validateJsonText(root, \"keyFormat\", true);\n        validateJsonText(root, \"agentNameCodec\", true);\n        validateJsonText(root, \"contentDigest\", false);\n        validateJsonText(root, \"mediaType\", false);\n        validateJsonInteger(root, \"schemaVersion\");\n        validateJsonInteger(root, \"size\");\n    }\n    \n    /**\n     * Validate an Agent Version storage descriptor against the internal storage schema.\n     *\n     * @param descriptor storage descriptor\n     * @throws IllegalArgumentException when the descriptor is invalid","sourceCodeStart":114,"sourceCodeEnd":150,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/ai/src/main/java/com/alibaba/nacos/ai/service/agent/storage/AgentVersionStorageDescriptorSerializer.java#L114-L150","documentation":"The parsed JSON object contains a key that is not in the allowed FIELDS set {provider, key, keyFormat, agentNameCodec, contentDigest, mediaType, schemaVersion, size}. The serializer uses a strict allow-list to reject typos and unexpected keys, keeping the storage schema stable and forward-compatible.","triggerScenarios":"deserialize() of a descriptor JSON with an extra field, e.g. {\"...\",\"extra\":true}, or a typo such as \"provide\":\"nacos_config\". Also triggered by a newer server writing a field an older server does not recognize.","commonSituations":"Mixed Nacos versions in a cluster where a newer writer adds a field; a manual edit adding a non-schema field; a custom storage-provider integration writing extra metadata into the descriptor.","solutions":["Remove the unknown field from the stored JSON so it contains only the eight schema fields","Upgrade all servers in the cluster to a Nacos version that recognizes the field","Re-publish the version so the current-schema writer regenerates the descriptor"],"exampleFix":"// before\n{\"provider\":\"nacos_config\",...,\"extra\":true}\n// after\n{\"provider\":\"nacos_config\",...}","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n    AgentVersionStorageDescriptorSerializer.deserialize(json);\n} catch (IllegalArgumentException e) {\n    // log the offending field name from the message, then surface a controlled error\n    throw new NacosException(NacosException.SERVER_ERROR, \"Unknown field in storage descriptor\", e);\n}","preventionTips":["Only write descriptors through AgentVersionStorageDescriptorSerializer.serialize","Keep all servers in the cluster on one Nacos version to avoid field-set mismatches"],"tags":["java","nacos","ai-agent","validation","json","schema","storage-descriptor"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}