{"record":{"id":"99735e47baf360a6","repo":"alibaba/spring-ai-alibaba","slug":"cannot-instantiate-array-type","errorCode":null,"errorMessage":"Cannot instantiate array type: {}","messagePattern":"Cannot instantiate array type: (.+?)","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"spring-ai-alibaba-graph-core/src/main/java/com/alibaba/cloud/ai/graph/serializer/plain_text/jackson/JacksonDeserializer.java","lineNumber":489,"sourceCode":"\t\t\t\t}\n\t\t\t\t\n\t\t\t\tif (element == null && !componentType.isPrimitive()) {\n\t\t\t\t\tArray.set(typedArray, i, null);\n\t\t\t\t\tcontinue;\n\t\t\t\t}\n\t\t\t\tif (element != null && !componentType.isInstance(element)) {\n\t\t\t\t\t// Type mismatch, fall back to generic Object array\n\t\t\t\t\tObjectMapper mapperNoTyping = objectMapper.copy();\n\t\t\t\t\tmapperNoTyping.setDefaultTyping(null);\n\t\t\t\t\tmapperNoTyping.deactivateDefaultTyping();\n\t\t\t\t\treturn payload.traverse(mapperNoTyping).readValueAs(Object[].class);\n\t\t\t\t}\n\t\t\t\tArray.set(typedArray, i, element);\n\t\t\t}\n\t\t\treturn typedArray;\n\t\t}\n\t\tcatch (ClassNotFoundException ex) {\n\t\t\tthrow new IllegalStateException(\"Cannot instantiate array type: \" + className, ex);\n\t\t}\n\t}\n\n\t/**\n\t * Reconstruct a primitive array that Jackson's WRAPPER_ARRAY default typing serialized\n\t * with a scalar (non-array) payload. Notably {@code byte[]} is written as a base64\n\t * string and {@code char[]} as a plain string. Delegating to Jackson preserves the\n\t * exact array type so values such as Gemini {@code thoughtSignatures} ({@code List<byte[]>})\n\t * survive a serialize/clone round-trip.\n\t * @param className the serialized component type id (e.g. {@code [B} or {@code byte[]})\n\t * @param payload the scalar payload node\n\t * @param objectMapper the ObjectMapper to bind with\n\t * @return the reconstructed array\n\t * @throws IOException if binding fails\n\t */\n\tprivate static Object instantiateScalarPayloadArray(String className, JsonNode payload, ObjectMapper objectMapper)\n\t\t\tthrows IOException {\n\t\ttry {","sourceCodeStart":471,"sourceCodeEnd":507,"githubUrl":"https://github.com/alibaba/spring-ai-alibaba/blob/f82da0b50f35744c13968191be2b1cd2452ef550/spring-ai-alibaba-graph-core/src/main/java/com/alibaba/cloud/ai/graph/serializer/plain_text/jackson/JacksonDeserializer.java#L471-L507","documentation":"JacksonDeserializer failed to load the array Class while reconstructing a typed array during state deserialization. Class.forName threw ClassNotFoundException for the recorded array component/type name, so the deserializer cannot allocate the array via Array.newInstance. This indicates the serialized state references an array type not present on the classpath or recorded in an unexpected format.","triggerScenarios":"deserializeArrayNode -> instantiateArray: the WRAPPER_ARRAY type id names an array type whose class cannot be loaded (e.g. custom class deleted/renamed, different classloader, or a type name format resolveArrayClass does not map).","commonSituations":"Loading checkpoints/saver files written by an older or different version of the app where the array element class was renamed or moved; running deserialization in a module that lacks the element class on the classpath; corrupted className strings in serialized state.","solutions":["Ensure the array element class exists on the classpath with the exact same fully-qualified name used at serialization time","Check the className in the serialized payload; array names must be JVM format like '[Ljava.lang.String;' or 'String[]' style","Re-serialize state with the current application version instead of reusing old checkpoints","If custom classes changed packages, migrate/rewrite old persisted state or keep a compatibility class"],"exampleFix":"// before: state checkpoint references com.example.OldDto[] which no longer exists\n// after: keep the class or add a compatibility alias\npackage com.example;\npublic class OldDto { /* legacy shape kept for checkpoint compat */ }\n// or regenerate the checkpoint with the current model classes","handlingStrategy":"validation","validationCode":"try { Class.forName(componentClassName); } catch (ClassNotFoundException e) { throw new IllegalStateException(\"Checkpoint references missing class: \" + componentClassName, e); }","typeGuard":"boolean isArrayTypeLoadable(String name) {\n    try { resolveArrayClassLike(name); return true; } catch (Throwable t) { return false; }\n}","tryCatchPattern":"try { state = deserializer.load(input); } catch (IllegalStateException e) { if (e.getMessage().startsWith(\"Cannot instantiate array type\")) { /* rebuild from fresh checkpoint */ } else throw e; }","preventionTips":["Keep element classes stable across releases; if renaming, write checkpoint migration tooling","Serialize and deserialize within the same classloader context in modular apps","Test checkpoint round-trips in CI after every model-class change"],"tags":["deserialization","reflection","classpath"],"backgroundTag":"class-not-found","analyzedSha":"f82da0b50f35744c13968191be2b1cd2452ef550","analyzedAt":"2026-09-09T15:32:42.421Z","contentChangedAt":"2026-09-09T15:32:42.421Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}