alibaba/nacos · error · NacosException

SERVER_ERROR

SERVER_ERROR

Error message

Agent Version content cannot be saved

What it means

Thrown by AgentVersionStorageService.save(PreparedAgentVersionWrite) when persisting prepared Agent Version bytes fails. The method routes to the selected AiResourceStorage and calls its save(); any IllegalArgumentException surfaced during routing (blank StorageKey.provider) or from the storage implementation's own save() (rejected content/key) is wrapped into a SERVER_ERROR NacosException. This is an internal persistence failure, not a caller-input problem.

Source

Thrown at ai/src/main/java/com/alibaba/nacos/ai/service/agent/storage/AgentVersionStorageService.java:142

    /**
     * Save content that was previously returned by {@link #prepare(String, String, String,
     * AgentVersionContent)}.
     *
     * <p>The provider and key captured during preparation are used even when the current storage
     * provider configuration has changed.</p>
     *
     * @param prepared prepared Agent Version content
     * @throws NacosException when the selected storage provider fails
     */
    public void save(PreparedAgentVersionWrite prepared) throws NacosException {
        if (prepared == null) {
            throw new IllegalArgumentException("Prepared Agent Version content must not be null");
        }
        StorageKey storageKey = prepared.getStorageKey();
        try {
            route(storageKey).save(storageKey, prepared.getBytes());
        } catch (IllegalArgumentException e) {
            throw new NacosException(NacosException.SERVER_ERROR,
                "Agent Version content cannot be saved", e);
        }
    }
    
    /**
     * Read, verify, and deserialize one Agent Version content object.
     *
     * <p>Size and digest are checked against the exact bytes returned by AI Storage before JSON
     * decoding. Unverified content is never returned.</p>
     *
     * @param descriptor Version storage pointer
     * @return verified Agent Version content
     * @throws NacosException when content is missing, corrupted, or cannot be read
     */
    public AgentVersionContent load(AgentVersionStorageDescriptor descriptor)
        throws NacosException {
        StorageKey storageKey = checkedStorageKey(descriptor);
        byte[] bytes;

View on GitHub (pinned to 9b989acdf1)

Solutions

  1. Inspect the wrapped cause (NacosException.getCause()) to see which IllegalArgumentException fired and its message — it identifies whether routing or the storage save rejected the write.
  2. Ensure the PreparedAgentVersionWrite passed to save() was produced by AgentVersionStorageService.prepare(...) so its StorageKey (provider + key) is valid and non-blank.
  3. Verify the AgentVersionContent object is well-formed before preparation (non-null kind, schemaVersion, valid JSON-serializable fields) so the serializer does not emit bytes the storage rejects.
  4. If the storage implementation imposes size/format limits, reduce the content payload or switch to a storage provider that accepts it.

Example fix

// before
AgentVersionStorageDescriptor desc = new AgentVersionStorageDescriptor();
desc.setProvider(""); // blank provider
PreparedAgentVersionWrite prepared = service.prepare(ns, agent, ver, content);
service.save(prepared); // fails: IllegalArgumentException from routing

// after
// Always go through prepare(); it resolves the provider from config
PreparedAgentVersionWrite prepared = service.prepare(ns, agent, ver, content);
service.save(prepared);
Defensive patterns

Strategy: try-catch

Validate before calling

// Validate before save
if (prepared == null) {
    throw new IllegalArgumentException("prepared must not be null");
}
if (prepared.getStorageKey() == null
    || StringUtils.isBlank(prepared.getStorageKey().getProvider())) {
    throw new IllegalStateException("StorageKey.provider is blank; rebuild via prepare()");
}
if (prepared.getBytes() == null || prepared.getBytes().length == 0) {
    throw new IllegalArgumentException("Serialized content is empty");
}

Try / catch

try {
    versionStorageService.save(prepared);
} catch (NacosException e) {
    if (e.getErrCode() == NacosException.SERVER_ERROR) {
        Throwable cause = e.getCause();
        log.error("Agent Version save failed: {}", cause != null ? cause.getMessage() : e.getMessage(), e);
    }
    throw e;
}

Prevention

When it happens

Trigger: Calling AgentVersionStorageService.save(prepared) or the convenience overload save(namespaceId, agentName, version, content) where the resolved StorageKey has a blank provider, or the underlying AiResourceStorage.save() throws IllegalArgumentException because the content bytes or key violate provider-specific invariants.

Common situations: A PreparedAgentVersionWrite was built from a stale or hand-constructed descriptor whose provider field is empty; the configured storage plugin rejects oversized or malformed serialized content; the AgentVersionContentSerializer produced bytes the storage layer cannot accept.

Related errors

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