{"record":{"id":"1ff8639f2c62d25f","repo":"alibaba/nacos","slug":"stored-agent-versioninfo-must-not-be-null","errorCode":null,"errorMessage":"Stored Agent versionInfo must not be null","messagePattern":"Stored Agent versionInfo must not be null","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"critical","filePath":"ai/src/main/java/com/alibaba/nacos/ai/service/agent/AgentPersistenceService.java","lineNumber":1258,"sourceCode":"        }\n    }\n    \n    private ResourceVersionInfo toResourceVersionInfo(AgentVersionInfo source) {\n        if (source == null) {\n            throw new IllegalArgumentException(\"Agent versionInfo must not be null\");\n        }\n        ResourceVersionInfo result = new ResourceVersionInfo();\n        result.setEditingVersion(source.getEditingVersion());\n        result.setReviewingVersion(source.getReviewingVersion());\n        result.setOnlineCnt(source.getOnlineCnt());\n        result.setLabels(source.getLabels() == null ? null\n            : new HashMap<String, String>(source.getLabels()));\n        return result;\n    }\n    \n    private AgentVersionInfo toAgentVersionInfo(ResourceVersionInfo source) {\n        if (source == null) {\n            throw new IllegalArgumentException(\"Stored Agent versionInfo must not be null\");\n        }\n        AgentVersionInfo result = new AgentVersionInfo();\n        result.setEditingVersion(source.getEditingVersion());\n        result.setReviewingVersion(source.getReviewingVersion());\n        result.setOnlineCnt(source.getOnlineCnt());\n        result.setLabels(source.getLabels() == null ? null\n            : new HashMap<String, String>(source.getLabels()));\n        return result;\n    }\n    \n    private AiResource toResourceRow(Agent agent) {\n        AgentResourceExt resourceExt = new AgentResourceExt();\n        resourceExt.setSchemaVersion(AgentResourceExt.SCHEMA_VERSION);\n        resourceExt.setDisplayName(agent.getDisplayName());\n        resourceExt.setIconUrl(agent.getIconUrl());\n        resourceExt.setProvider(agent.getProvider());\n        resourceExt.setExtensions(agent.getExtensions());\n        resourceExt.setVersionCatalog(agent.getVersionCatalog());","sourceCodeStart":1240,"sourceCodeEnd":1276,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/ai/src/main/java/com/alibaba/nacos/ai/service/agent/AgentPersistenceService.java#L1240-L1276","documentation":"When converting a stored ResourceVersionInfo back to an AgentVersionInfo during an Agent read, the source must not be null. This guard in toAgentVersionInfo fires when AiResourceManager.requireVersionInfo(row) returns null, indicating the Resource row's versionInfo JSON column is missing or deserialized to null.","triggerScenarios":"Any Agent read (GET, list, summary) where the AiResource.versionInfo column is null, empty, or deserializes to a null ResourceVersionInfo. Called from toAgent (line 1323) and toAgentSummary (line 1345) via AiResourceManager.requireVersionInfo.","commonSituations":"Direct database manipulation cleared the versionInfo column. A partial write or crashed transaction left the Resource row without version info. A migration created Resource rows without populating versionInfo. A data consistency bug between the versionInfo JSON and the version rows.","solutions":["Inspect the AiResource.versionInfo column for the affected Agent and repair it to a valid ResourceVersionInfo JSON.","If the Agent has online versions, reconstruct versionInfo with the correct editingVersion, reviewingVersion, onlineCnt, and labels.","If the Agent is unrecoverable, delete and recreate it through the Admin API.","Run a data-integrity audit to find Resource rows with missing versionInfo."],"exampleFix":"-- SQL repair: reconstruct versionInfo from version rows\nUPDATE ai_resource SET version_info = '{\"editingVersion\":null,\"reviewingVersion\":null,\"onlineCnt\":1,\"labels\":{}}'\nWHERE version_info IS NULL AND type = 'agent';","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n    Agent agent = persistenceService.getAgent(ns, name);\n} catch (NacosException e) {\n    if (e.getCause() instanceof IllegalArgumentException\n        && e.getMessage().contains(\"versionInfo must not be null\")) {\n        // repair versionInfo column, then retry\n    }\n    throw e;\n}","preventionTips":["Never clear the versionInfo column directly — use the Admin API for lifecycle operations.","Monitor for Resource rows with null versionInfo as a data-integrity alert.","Validate versionInfo after migrations and crashed-transaction recovery."],"tags":["agent","ai-registry","data-integrity","version-info","deserialization"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}