{"record":{"id":"f3c120401d51c282","repo":"spring-projects/spring-ai","slug":"failed-to-parse-metadata-json-using-empty-metadat","errorCode":null,"errorMessage":"Failed to parse metadata JSON. Using empty metadata. json=${metadataJson}","messagePattern":"Failed to parse metadata JSON\\. Using empty metadata\\. json=(.+?)","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"vector-stores/spring-ai-azure-store/src/main/java/org/springframework/ai/vectorstore/azure/AzureVectorStore.java","lineNumber":352,"sourceCode":"\t}\n\n\t@Override\n\tpublic <T> Optional<T> getNativeClient() {\n\t\t@SuppressWarnings(\"unchecked\")\n\t\tT client = (T) this.searchClient;\n\t\treturn Optional.of(client);\n\t}\n\n\tstatic Map<String, Object> parseMetadataToMutable(@Nullable String metadataJson) {\n\t\tif (!StringUtils.hasText(metadataJson)) {\n\t\t\treturn new HashMap<>();\n\t\t}\n\t\ttry {\n\t\t\treturn new HashMap<>(jsonHelper.fromJsonToMap(metadataJson));\n\t\t}\n\t\tcatch (IllegalStateException ex) {\n\t\t\tif (logger.isWarnEnabled()) {\n\t\t\t\tlogger.warn(\"Failed to parse metadata JSON. Using empty metadata. json=\" + metadataJson, ex);\n\t\t\t}\n\t\t\treturn new HashMap<>();\n\t\t}\n\t}\n\n\tpublic record MetadataField(String name, SearchFieldDataType fieldType) {\n\n\t\tpublic static MetadataField text(String name) {\n\t\t\treturn new MetadataField(name, SearchFieldDataType.STRING);\n\t\t}\n\n\t\tpublic static MetadataField int32(String name) {\n\t\t\treturn new MetadataField(name, SearchFieldDataType.INT32);\n\t\t}\n\n\t\tpublic static MetadataField int64(String name) {\n\t\t\treturn new MetadataField(name, SearchFieldDataType.INT64);\n\t\t}","sourceCodeStart":334,"sourceCodeEnd":370,"githubUrl":"https://github.com/spring-projects/spring-ai/blob/98a7beda4f29d80a71c5837eb4053b03a93a46f7/vector-stores/spring-ai-azure-store/src/main/java/org/springframework/ai/vectorstore/azure/AzureVectorStore.java#L334-L370","documentation":"AzureVectorStore parses each document's metadata from a JSON string stored in Azure AI Search. parseMetadataToMutable catches IllegalStateException from jsonHelper.fromJsonToMap, logs this warning with the offending JSON, and substitutes an empty metadata map so the document is still usable — only its metadata is lost.","triggerScenarios":"Reading documents from the Azure AI Search index whose metadata field contains malformed/non-JSON content, or content written by a different version/schema that no longer parses.","commonSituations":"Index populated by another application or older Spring AI version with a different metadata serialization; manual index edits; data corruption or truncation of the metadata JSON field; filter/query results returning raw fields.","solutions":["Inspect the logged json= value to see the malformed metadata and determine how it was written.","Re-write the affected documents so the metadata field contains valid JSON produced by AzureVectorStore.","Ensure all writers to the index use a compatible Spring AI version and the same metadata serialization.","If empty metadata is acceptable for corrupt records, no action needed — parsing degrades gracefully to an empty map."],"exampleFix":"// before: metadata field written as raw string\nindexClient.mergeOrUploadDocument(doc with metadata=\"category: travel\");\n// after: valid JSON only\nindexClient.mergeOrUploadDocument(doc with metadata=\"{\\\"category\\\":\\\"travel\\\"}\");","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"// library catches internally; on your side guard downstream metadata use:\nMap<String,Object> meta = doc.getMetadata();\nString category = meta.containsKey(\"category\") ? (String) meta.get(\"category\") : DEFAULT_CATEGORY;","preventionTips":["Write metadata to Azure AI Search only via AzureVectorStore so it is valid JSON.","Keep all writers to the index on the same Spring AI version.","Alert on this warning in production logs — it indicates corrupt/foreign records.","Handle documents with empty metadata gracefully in application code."],"tags":["azure","vector-store","json","metadata","graceful-degradation"],"backgroundTag":"json-parse-error","analyzedSha":"98a7beda4f29d80a71c5837eb4053b03a93a46f7","analyzedAt":"2026-09-11T14:15:49.441Z","contentChangedAt":"2026-09-11T14:15:49.441Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}