alibaba/nacos · critical · IllegalArgumentException

Stored Agent versionInfo must not be null

Error message

Stored Agent versionInfo must not be null

What it means

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.

Source

Thrown at ai/src/main/java/com/alibaba/nacos/ai/service/agent/AgentPersistenceService.java:1258

        }
    }
    
    private ResourceVersionInfo toResourceVersionInfo(AgentVersionInfo source) {
        if (source == null) {
            throw new IllegalArgumentException("Agent versionInfo must not be null");
        }
        ResourceVersionInfo result = new ResourceVersionInfo();
        result.setEditingVersion(source.getEditingVersion());
        result.setReviewingVersion(source.getReviewingVersion());
        result.setOnlineCnt(source.getOnlineCnt());
        result.setLabels(source.getLabels() == null ? null
            : new HashMap<String, String>(source.getLabels()));
        return result;
    }
    
    private AgentVersionInfo toAgentVersionInfo(ResourceVersionInfo source) {
        if (source == null) {
            throw new IllegalArgumentException("Stored Agent versionInfo must not be null");
        }
        AgentVersionInfo result = new AgentVersionInfo();
        result.setEditingVersion(source.getEditingVersion());
        result.setReviewingVersion(source.getReviewingVersion());
        result.setOnlineCnt(source.getOnlineCnt());
        result.setLabels(source.getLabels() == null ? null
            : new HashMap<String, String>(source.getLabels()));
        return result;
    }
    
    private AiResource toResourceRow(Agent agent) {
        AgentResourceExt resourceExt = new AgentResourceExt();
        resourceExt.setSchemaVersion(AgentResourceExt.SCHEMA_VERSION);
        resourceExt.setDisplayName(agent.getDisplayName());
        resourceExt.setIconUrl(agent.getIconUrl());
        resourceExt.setProvider(agent.getProvider());
        resourceExt.setExtensions(agent.getExtensions());
        resourceExt.setVersionCatalog(agent.getVersionCatalog());

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Inspect the AiResource.versionInfo column for the affected Agent and repair it to a valid ResourceVersionInfo JSON.
2. If the Agent has online versions, reconstruct versionInfo with the correct editingVersion, reviewingVersion, onlineCnt, and labels.
3. If the Agent is unrecoverable, delete and recreate it through the Admin API.
4. Run a data-integrity audit to find Resource rows with missing versionInfo.

Example fix

-- SQL repair: reconstruct versionInfo from version rows
UPDATE ai_resource SET version_info = '{"editingVersion":null,"reviewingVersion":null,"onlineCnt":1,"labels":{}}'
WHERE version_info IS NULL AND type = 'agent';

try {
    Agent agent = persistenceService.getAgent(ns, name);
} catch (NacosException e) {
    if (e.getCause() instanceof IllegalArgumentException
        && e.getMessage().contains("versionInfo must not be null")) {
        // repair versionInfo column, then retry
    }
    throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Invalid persisted Agent tags
• Persisted Agent tags must be a JSON array
• Persisted Agent tags must contain only strings
• Invalid AgentResourceExt
• AgentResourceExt JSON must not be empty

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