spring-projects/spring-ai · error · RuntimeException

Failed to create Index

Error message

Failed to create Index

What it means

createIndex builds a vector index on the embedding field and throws a plain RuntimeException("Failed to create Index") when the createIndex RPC returns an exception. Without the index, similarity search cannot run efficiently or at all.

Source

Thrown at vector-stores/spring-ai-milvus-store/src/main/java/org/springframework/ai/vectorstore/milvus/MilvusVectorStore.java:568

			throw new RuntimeException("Failed to create collection", collectionStatus.getException());
		}

	}

	void createIndex(String databaseName, String collectionName, String embeddingFieldName, IndexType indexType,
			MetricType metricType, String indexParameters) {
		R<RpcStatus> indexStatus = this.milvusClient.createIndex(CreateIndexParam.newBuilder()
			.withDatabaseName(databaseName)
			.withCollectionName(collectionName)
			.withFieldName(embeddingFieldName)
			.withIndexType(indexType)
			.withMetricType(metricType)
			.withExtraParam(indexParameters)
			.withSyncMode(Boolean.FALSE)
			.build());

		if (indexStatus.getException() != null) {
			throw new RuntimeException("Failed to create Index", indexStatus.getException());
		}
	}

	int embeddingDimensions() {
		if (this.embeddingDimension != INVALID_EMBEDDING_DIMENSION) {
			return this.embeddingDimension;
		}
		try {
			int embeddingDimensions = this.embeddingModel.dimensions();
			if (embeddingDimensions > 0) {
				return embeddingDimensions;
			}
		}
		catch (Exception e) {
			if (logger.isWarnEnabled()) {
				logger.warn(
						"Failed to obtain the embedding dimensions from the embedding model and fall backs to default: "
								+ this.embeddingDimension,

View on GitHub (pinned to 98a7beda4f)

Solutions

1. Read the cause exception for the Milvus status message.
2. Validate the indexParameters JSON string is well-formed and matches the index type.
3. Ensure the configured IndexType/MetricType combination is supported by your Milvus server version.
4. Confirm the embedding field name matches the schema created in createCollection.
5. Retry index creation after collection state settles (SyncMode is false, creation is async).

Example fix

// before
.indexParameters("{ 'nlist': }") // malformed JSON
// after
.indexParameters("{ 'nlist': 16384 }")

// validate index parameters JSON before configuring the store
String params = "{ \"nlist\": 16384 }";
try {
    new ObjectMapper().readTree(params); // throws if malformed
} catch (Exception e) {
    throw new IllegalArgumentException("Invalid indexParameters JSON", e);
}

try {
    MilvusVectorStore store = MilvusVectorStore.builder(milvusClient)
        .indexType(IndexType.IVF_FLAT).metricType(MetricType.COSINE)
        .indexParameters("{ \"nlist\": 16384 }").build();
} catch (RuntimeException e) {
    logger.error("Index creation failed: {}", e.getCause() != null ? e.getCause().getMessage() : e.getMessage());
}

When it happens

Trigger: Called by createCollection during initialization when milvusClient.createIndex fails: invalid indexParameters JSON, unsupported IndexType/MetricType combination for the Milvus version, or wrong embedding field name.

Common situations: Index parameters JSON (e.g. {"nlist":16384}) malformed; HNSW/IVF metric type not supported by the deployed Milvus; custom metricType/indexType config values invalid.

Related errors

• Index %s does not exist in table %s
• Collection loading failed!
• Failed to create collection
• Drop Index failed!
• Failed to invoke ensureIndex() method

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