{"record":{"id":"b55afa518f130161","repo":"alibaba/spring-ai-alibaba","slug":"metadata-must-be-an-object","errorCode":null,"errorMessage":"Metadata must be an object","messagePattern":"Metadata must be an object","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/SerializationHelper.java","lineNumber":74,"sourceCode":"import com.fasterxml.jackson.databind.util.TokenBuffer;\n\nclass SerializationHelper {\n\n\tstatic final String METADATA_FIELD = \"metadata\";\n\n\tstatic Map<String, Object> deserializeMetadata(ObjectMapper mapper, JsonNode parentNode)\n\t\t\tthrows JsonProcessingException {\n\t\tif (parentNode == null) {\n\t\t\treturn Map.of();\n\t\t}\n\n\t\tvar node = parentNode.findValue(METADATA_FIELD);\n\n\t\tif (node == null || node.isNull() || node.isEmpty()) {\n\t\t\treturn Map.of();\n\t\t}\n\t\tif (!node.isObject()) {\n\t\t\tthrow new IllegalStateException(\"Metadata must be an object\");\n\t\t}\n\t\treturn mapper.treeToValue(node, new TypeReference<>() {\n\t\t});\n\t}\n\n\tstatic void serializeMetadata(JsonGenerator gen, SerializerProvider provider, Map<String, Object> metadata)\n\t\t\tthrows IOException {\n\t\tgen.writeObjectField(METADATA_FIELD, normalizeMetadataValue(provider, metadata));\n\t}\n\n\tprivate static Object normalizeMetadataValue(SerializerProvider provider, Object value) throws IOException {\n\t\treturn normalizeMetadataValue(provider, value, JsonInclude.Include.ALWAYS);\n\t}\n\n\tprivate static Object normalizeMetadataValue(SerializerProvider provider, Object value,\n\t\t\tJsonInclude.Include contentInclusion) throws IOException {\n\t\tif (value instanceof Map<?, ?> map) {\n\t\t\tboolean preserveContainer = hasClassSerializationOverrides(provider, map.getClass());","sourceCodeStart":56,"sourceCodeEnd":92,"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/SerializationHelper.java#L56-L92","documentation":"deserializeMetadata expects the 'metadata' JSON field of a serialized state/graph to be a JSON object that maps to Map<String,Object>. If the field exists but is a scalar, array, or other non-object node, the deserializer aborts with IllegalStateException because metadata cannot be represented otherwise.","triggerScenarios":"Loading a checkpoint/serialized state whose 'metadata' field is present but is a JSON scalar, string, or array instead of an object — typically from hand-editing, cross-version formats, or corrupt files.","commonSituations":"Manually written checkpoint JSON; metadata written by another tool/version with a different shape; truncated or concatenated JSON files.","solutions":["Open the serialized file and make the 'metadata' field a JSON object ({...}) or remove it entirely (null/missing yields an empty map)","Re-export the state with the same library version that wrote it originally","If migrating formats, transform old metadata representation into a key/value object before loading","Validate checkpoint JSON with a schema check (metadata: object|null) before loading"],"exampleFix":"// before\n\"metadata\": \"user-uploads\"\n// after\n\"metadata\": {\"owner\": \"user-uploads\"}","handlingStrategy":"validation","validationCode":"JsonNode meta = root.get(\"metadata\");\nif (meta != null && !meta.isNull() && !meta.isObject()) throw new IllegalArgumentException(\"metadata must be a JSON object\");","typeGuard":"boolean isObjectNode(JsonNode n) { return n == null || n.isNull() || n.isObject(); }","tryCatchPattern":"try { loaded = loader.load(file); } catch (IllegalStateException e) { if (\"Metadata must be an object\".equals(e.getMessage())) { /* repair or regenerate the checkpoint */ } else throw e; }","preventionTips":["Validate checkpoint JSON against a schema before loading","Do not hand-edit serialized state files","When migrating formats, transform metadata to a key/value object explicitly"],"tags":["deserialization","json","metadata"],"backgroundTag":"unexpected-response-shape","analyzedSha":"f82da0b50f35744c13968191be2b1cd2452ef550","analyzedAt":"2026-09-09T15:32:42.421Z","contentChangedAt":"2026-09-09T15:32:42.421Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}