spring-projects/spring-ai · error · RuntimeException

Failed to create collection

Error message

Failed to create collection

What it means

createCollection calls milvusClient.createCollection and throws a plain RuntimeException("Failed to create collection") when the RPC response carries an exception. The collection schema (ID, content, metadata, embedding fields) could not be created on the Milvus server.

Source

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

			.build();

		CreateCollectionParam createCollectionReq = CreateCollectionParam.newBuilder()
			.withDatabaseName(databaseName)
			.withCollectionName(collectionName)
			.withDescription("Spring AI Vector Store")
			.withConsistencyLevel(ConsistencyLevelEnum.STRONG)
			.withShardsNum(2)
			.withSchema(CollectionSchemaParam.newBuilder()
				.addFieldType(docIdFieldType)
				.addFieldType(contentFieldType)
				.addFieldType(metadataFieldType)
				.addFieldType(embeddingFieldType)
				.build())
			.build();

		R<RpcStatus> collectionStatus = this.milvusClient.createCollection(createCollectionReq);
		if (collectionStatus.getException() != null) {
			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());

View on GitHub (pinned to 98a7beda4f)

Solutions

1. Read the cause exception for the exact Milvus error status.
2. Check whether the collection already exists with a conflicting schema — drop it or reuse it.
3. Verify the collection name is valid (letters, digits, underscores).
4. Confirm field types (JSON metadata field support) match your Milvus server version.
5. Ensure the target database exists.

Example fix

// before
// initializeSchema(true) fails because collection exists with old schema
// after
// drop the outdated collection once, then let the store recreate it
milvusClient.dropCollection(DropCollectionParam.newBuilder().withCollectionName("vector_store").build());
MilvusVectorStore.builder(milvusClient).initializeSchema(true).build();

// detect a pre-existing collection with a conflicting schema before initializeSchema runs
boolean exists = milvusClient.hasCollection(HasCollectionParam.newBuilder()
        .withCollectionName(collectionName).build()).getData(Boolean.FALSE);
if (exists) {
    // describe and compare schema fields, or drop if incompatible
    milvusClient.describeCollection(DescribeCollectionParam.newBuilder().withCollectionName(collectionName).build());
}

try {
    MilvusVectorStore store = MilvusVectorStore.builder(milvusClient).initializeSchema(true).build();
} catch (RuntimeException e) {
    logger.error("Collection creation failed: {}", e.getCause() != null ? e.getCause().getMessage() : e.getMessage());
}

When it happens

Trigger: Called from afterPropertiesSet (initializeSchema) or shouldFilterWithCustomMetadataFieldName when creating the collection fails: collection already exists with a different schema, invalid field types, reserved/illegal collection name, or server-side error.

Common situations: Collection already exists from a prior run with an incompatible schema; illegal characters in collection name; Milvus server version mismatch on supported field types.

Related errors

• Collection loading failed!
• Collection {collectionName} with the tenant: {tenantName} an
• Failed to create Index
• Release collection failed!
• Drop Collection failed!

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