{"record":{"id":"c84afc0274dc114b","repo":"alibaba/nacos","slug":"agent-version-storage-descriptor-must-not-be-null","errorCode":null,"errorMessage":"Agent Version storage descriptor must not be null","messagePattern":"Agent Version storage descriptor must not be null","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"ai/src/main/java/com/alibaba/nacos/ai/service/agent/storage/AgentVersionStorageDescriptorSerializer.java","lineNumber":154,"sourceCode":"        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\n     */\n    public static void validate(AgentVersionStorageDescriptor descriptor) {\n        if (descriptor == null) {\n            throw new IllegalArgumentException(\"Agent Version storage descriptor must not be null\");\n        }\n        String provider = descriptor.getProvider();\n        if (provider == null || provider.length() > MAX_PROVIDER_LENGTH\n            || !PROVIDER_PATTERN.matcher(provider).matches()) {\n            throw new IllegalArgumentException(\"Invalid Agent Version storage provider\");\n        }\n        validateRequiredText(\"key\", descriptor.getKey(), MAX_KEY_LENGTH);\n        validateOptionalText(\"keyFormat\", descriptor.getKeyFormat(), MAX_FORMAT_LENGTH);\n        validateOptionalText(\"agentNameCodec\", descriptor.getAgentNameCodec(), MAX_FORMAT_LENGTH);\n        if (descriptor.getContentDigest() == null\n            || !DIGEST_PATTERN.matcher(descriptor.getContentDigest()).matches()) {\n            throw new IllegalArgumentException(\"Invalid Agent Version contentDigest\");\n        }\n        if (!AGENT_VERSION_MEDIA_TYPE.equals(descriptor.getMediaType())) {\n            throw new IllegalArgumentException(\"Agent Version mediaType must be \"\n                + AGENT_VERSION_MEDIA_TYPE);\n        }\n        if (!Integer.valueOf(SCHEMA_VERSION).equals(descriptor.getSchemaVersion())) {","sourceCodeStart":136,"sourceCodeEnd":172,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/ai/src/main/java/com/alibaba/nacos/ai/service/agent/storage/AgentVersionStorageDescriptorSerializer.java#L136-L172","documentation":"Thrown by validate() when the AgentVersionStorageDescriptor object itself is null. It guards serialize(null), validate(null), AgentVersionStorageService.prepare(null, content), and the PreparedAgentVersionWrite constructor before any field is accessed.","triggerScenarios":"AgentVersionStorageDescriptorSerializer.serialize(null), validate(null), or AgentVersionStorageService.prepare(null, content). Reached when a code path conditionally builds a descriptor and passes null through.","commonSituations":"A draft flow that has no prepared content yet; a conditional builder that returns null on an edge case; a missing null check before persisting.","solutions":["Guarantee the descriptor is constructed before calling serialize/validate","Build the descriptor via AgentVersionStorageService.prepare(...) which always returns a non-null descriptor","Add an explicit null check and fail fast with a domain-specific NacosException message"],"exampleFix":"// before\nString storage = AgentVersionStorageDescriptorSerializer.serialize(maybeNullDescriptor);\n// after\nif (descriptor == null) {\n    throw new NacosException(NacosException.SERVER_ERROR, \"Agent Version descriptor missing\");\n}\nString storage = AgentVersionStorageDescriptorSerializer.serialize(descriptor);","handlingStrategy":"validation","validationCode":"if (descriptor == null) {\n    throw new NacosException(NacosException.SERVER_ERROR,\n        \"Agent Version descriptor must not be null\");\n}\nAgentVersionStorageDescriptorSerializer.serialize(descriptor);","typeGuard":"private static boolean isValidDescriptor(AgentVersionStorageDescriptor d) {\n    return d != null;\n}","tryCatchPattern":null,"preventionTips":["Always build descriptors via AgentVersionStorageService.prepare, which never returns null","Add an explicit null check before persisting rather than relying on the serializer to fail"],"tags":["java","nacos","ai-agent","validation","null-input","storage-descriptor"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}