{"record":{"id":"f49f454221b66a5d","repo":"spring-projects/spring-ai","slug":"failed-to-serialize-the-document-metadata","errorCode":null,"errorMessage":"Failed to serialize the Document metadata: ","messagePattern":"Failed to serialize the Document metadata: ","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"vector-stores/spring-ai-weaviate-store/src/main/java/org/springframework/ai/vectorstore/weaviate/WeaviateVectorStore.java","lineNumber":250,"sourceCode":"\t\t\t}\n\t\t}\n\n\t\tif (!CollectionUtils.isEmpty(errorMessages)) {\n\t\t\tthrow new RuntimeException(\"Failed to add documents because: \\n\" + errorMessages);\n\t\t}\n\t}\n\n\tprivate WeaviateObject toWeaviateObject(Document document, List<Document> documents, List<float[]> embeddings) {\n\n\t\t// https://weaviate.io/developers/weaviate/config-refs/datatypes\n\t\tMap<String, Object> fields = new HashMap<>();\n\t\tfields.put(this.options.getContentFieldName(), document.getText());\n\t\ttry {\n\t\t\tString metadataString = JsonMapper.shared().writeValueAsString(document.getMetadata());\n\t\t\tfields.put(METADATA_FIELD_NAME, metadataString);\n\t\t}\n\t\tcatch (JacksonException e) {\n\t\t\tthrow new RuntimeException(\"Failed to serialize the Document metadata: \" + document.getText());\n\t\t}\n\n\t\t// Add the filterable metadata fields as top level fields, allowing filler\n\t\t// expressions on them.\n\t\tfor (MetadataField mf : this.filterMetadataFields) {\n\t\t\tif (document.getMetadata().containsKey(mf.name())) {\n\t\t\t\tfields.put(this.options.getMetaFieldPrefix() + mf.name(), document.getMetadata().get(mf.name()));\n\t\t\t}\n\t\t}\n\n\t\treturn WeaviateObject.builder()\n\t\t\t.className(this.options.getObjectClass())\n\t\t\t.id(document.getId())\n\t\t\t.vector(EmbeddingUtils.toFloatArray(embeddings.get(documents.indexOf(document))))\n\t\t\t.properties(fields)\n\t\t\t.build();\n\t}\n","sourceCodeStart":232,"sourceCodeEnd":268,"githubUrl":"https://github.com/spring-projects/spring-ai/blob/98a7beda4f29d80a71c5837eb4053b03a93a46f7/vector-stores/spring-ai-weaviate-store/src/main/java/org/springframework/ai/vectorstore/weaviate/WeaviateVectorStore.java#L232-L268","documentation":"In toWeaviateObject(), the Document's metadata map is serialized to JSON with JsonMapper before being stored in Weaviate. If Jackson fails (JacksonException), the store throws a RuntimeException naming the document text. Non-serializable metadata values are the cause.","triggerScenarios":"Calling VectorStore.add(List<Document>) with a Document whose metadata map contains values Jackson cannot write — e.g. raw Object instances, LocalDateTime without JavaTimeModule, nested non-POJO types, or self-referencing structures.","commonSituations":"Putting LocalDateTime/Instant into metadata without registering the JavaTimeModule; embedding application domain objects in metadata instead of primitives/String/List; reading metadata from another store with incompatible types.","solutions":["Restrict metadata values to JSON-safe types (String, Number, Boolean, List of primitives).","Convert dates/times to ISO-8601 strings before adding: metadata.put(\"date\", localDate.toString()).","Flatten or toJsonString() any complex objects stored in metadata.","If needed, configure JsonMapper with modules (JavaTimeModule) — though the safest fix is sanitizing metadata at construction time."],"exampleFix":"// before\nmetadata.put(\"createdAt\", LocalDateTime.now());\n// after\nmetadata.put(\"createdAt\", LocalDateTime.now().toString()); // ISO-8601 string, Jackson-safe","handlingStrategy":"validation","validationCode":"docs.forEach(d -> { try { JsonMapper.shared().writeValueAsString(d.getMetadata()); } catch (Exception e) { throw new IllegalStateException(\"Document metadata not serializable: \" + d.getId(), e); } });","typeGuard":"boolean safeMetadata(Map<String,Object> m) { return m.values().stream().allMatch(v -> v instanceof String || v instanceof Number || v instanceof Boolean); }","tryCatchPattern":"try { vectorStore.add(docs); } catch (RuntimeException e) { if (e.getMessage().startsWith(\"Failed to serialize the Document metadata\")) { sanitizeAndRetry(docs); } }","preventionTips":["Never put LocalDateTime/Instant or domain objects in Document metadata; use ISO strings","Sanitize metadata at Document construction time","Add a unit test asserting metadata JSON round-trips through JsonMapper"],"tags":["weaviate","jackson","serialization","metadata"],"backgroundTag":"json-serialization-failed","analyzedSha":"98a7beda4f29d80a71c5837eb4053b03a93a46f7","analyzedAt":"2026-09-11T14:15:49.441Z","contentChangedAt":"2026-09-11T14:15:49.441Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}