Failed to parse metadata JSON. Using empty metadata. json=

Error message

Failed to parse metadata JSON. Using empty metadata. json=${metadataJson}

What it means

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.

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.

Example fix

// before: metadata field written as raw string
indexClient.mergeOrUploadDocument(doc with metadata="category: travel");
// after: valid JSON only
indexClient.mergeOrUploadDocument(doc with metadata="{\"category\":\"travel\"}");

Defensive patterns

Strategy: try-catch

Try / catch

// library catches internally; on your side guard downstream metadata use:
Map<String,Object> meta = doc.getMetadata();
String category = meta.containsKey("category") ? (String) meta.get("category") : DEFAULT_CATEGORY;

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: JSON parse error: "Unexpected token" / "not valid JSON" / "failed to parse" — what JSON parsers are really complaining about — this error's family across 45 libraries.

Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

AI-assisted analysis of spring-projects/spring-ai@98a7beda4f (2026-09-11). Data as JSON: /api/errors/f3c120401d51c282. Report an issue: GitHub.

Appendix: source

Thrown at vector-stores/spring-ai-azure-store/src/main/java/org/springframework/ai/vectorstore/azure/AzureVectorStore.java:352

	}

	@Override
	public <T> Optional<T> getNativeClient() {
		@SuppressWarnings("unchecked")
		T client = (T) this.searchClient;
		return Optional.of(client);
	}

	static Map<String, Object> parseMetadataToMutable(@Nullable String metadataJson) {
		if (!StringUtils.hasText(metadataJson)) {
			return new HashMap<>();
		}
		try {
			return new HashMap<>(jsonHelper.fromJsonToMap(metadataJson));
		}
		catch (IllegalStateException ex) {
			if (logger.isWarnEnabled()) {
				logger.warn("Failed to parse metadata JSON. Using empty metadata. json=" + metadataJson, ex);
			}
			return new HashMap<>();
		}
	}

	public record MetadataField(String name, SearchFieldDataType fieldType) {

		public static MetadataField text(String name) {
			return new MetadataField(name, SearchFieldDataType.STRING);
		}

		public static MetadataField int32(String name) {
			return new MetadataField(name, SearchFieldDataType.INT32);
		}

		public static MetadataField int64(String name) {
			return new MetadataField(name, SearchFieldDataType.INT64);
		}

View on GitHub (pinned to 98a7beda4f)