{"record":{"id":"5b9cb4c06929b598","repo":"alibaba/nacos","slug":"agentversioncontent-exceeds-max-content-size-byt","errorCode":null,"errorMessage":"AgentVersionContent exceeds {MAX_CONTENT_SIZE} bytes","messagePattern":"AgentVersionContent exceeds (.+?) bytes","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"ai/src/main/java/com/alibaba/nacos/ai/service/agent/storage/AgentVersionContentSerializer.java","lineNumber":92,"sourceCode":"    }\n    \n    /**\n     * Validate and serialize one Agent Version content object.\n     *\n     * @param content Agent Version content\n     * @return immutable serialized storage result\n     * @throws IllegalArgumentException when content is invalid or exceeds the storage limit\n     */\n    public static SerializedContent serialize(AgentVersionContent content) {\n        validate(content);\n        final byte[] bytes;\n        try {\n            bytes = JacksonUtils.toJsonBytes(toStorageProjection(content));\n        } catch (NacosSerializationException e) {\n            throw new IllegalArgumentException(\"Unable to serialize AgentVersionContent\", e);\n        }\n        if (bytes.length > MAX_CONTENT_SIZE) {\n            throw new IllegalArgumentException(\n                \"AgentVersionContent exceeds \" + MAX_CONTENT_SIZE + \" bytes\");\n        }\n        return new SerializedContent(bytes, digest(bytes));\n    }\n    \n    /**\n     * Compute the digest of the exact bytes read from or written to AI Storage.\n     *\n     * @param bytes persisted Agent Version content bytes\n     * @return digest token in {@code sha256:<lowercase hex>} form\n     * @throws IllegalArgumentException when bytes are null or exceed the storage limit\n     */\n    public static String digest(byte[] bytes) {\n        if (bytes == null) {\n            throw new IllegalArgumentException(\"AgentVersionContent bytes must not be null\");\n        }\n        if (bytes.length > MAX_CONTENT_SIZE) {\n            throw new IllegalArgumentException(","sourceCodeStart":74,"sourceCodeEnd":110,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/ai/src/main/java/com/alibaba/nacos/ai/service/agent/storage/AgentVersionContentSerializer.java#L74-L110","documentation":"Thrown by AgentVersionContentSerializer.serialize when the serialized JSON byte length of the AgentVersionContent storage projection exceeds MAX_CONTENT_SIZE (1 MiB = 1048576 bytes). This is a hard storage ceiling enforced after serialization so the limit applies to exact persisted bytes, not the in-memory model.","triggerScenarios":"Publishing or updating an Agent Version whose callInterfaces contain very large nativeDescriptor blobs, many declared endpoints, or large metadata maps such that the canonical JSON projection crosses 1 MiB.","commonSituations":"An agent descriptor (e.g. a full MCP tool catalog or OpenAPI spec embedded in nativeDescriptor) is too large. Also when a draft accumulates many call interfaces or endpoints near the 16-interface / 64-endpoint limits with bulky metadata.","solutions":["Reduce the size of nativeDescriptor payloads — store large specs externally and reference by URI instead of embedding.","Trim metadata maps and remove unused declared endpoints.","If the limit is genuinely too low for your use case, raise MAX_CONTENT_SIZE in AgentVersionContentSerializer and update the corresponding spec, but this is a storage-contract change requiring maintainer discussion."],"exampleFix":"// before\ncallInterface.setNativeDescriptor(hugeOpenApiJsonString); // >1 MiB\n\n// after\ncallInterface.setNativeDescriptor(referenceObjectWithUri); // small JSON object pointing to external spec","handlingStrategy":"validation","validationCode":"SerializedContent probe = AgentVersionContentSerializer.serialize(content);\n// serialize itself enforces the limit; to pre-check without serializing,\nestimate JSON size before building large descriptors and reject early.","typeGuard":null,"tryCatchPattern":"try {\n    return AgentVersionStorageService.save(ns, agent, version, content);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().contains(\"exceeds\")) {\n        return ApiErrors.payloadTooLarge(\"Agent Version content exceeds 1 MiB\");\n    }\n    throw e;\n}","preventionTips":["Keep nativeDescriptor under ~900 KiB to leave room for the JSON envelope.","Store large specs externally and embed only a reference.","Run a size check in CI on sample agent descriptors."],"tags":["capacity","agent-version","storage","illegal-argument"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}