{"record":{"id":"aeca22db85a68506","repo":"spring-projects/spring-ai","slug":"failed-to-insert","errorCode":null,"errorMessage":"Failed to insert:","messagePattern":"Failed to insert:","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"vector-stores/spring-ai-milvus-store/src/main/java/org/springframework/ai/vectorstore/milvus/MilvusVectorStore.java","lineNumber":293,"sourceCode":"\t\tif (!this.isAutoId) {\n\t\t\tfields.add(new InsertParam.Field(this.idFieldName, docIdArray));\n\t\t}\n\t\tfields.add(new InsertParam.Field(this.contentFieldName, contentArray));\n\t\tfields.add(new InsertParam.Field(this.metadataFieldName, metadataArray));\n\t\tfields.add(new InsertParam.Field(this.embeddingFieldName, embeddingArray));\n\n\t\tInsertParam.Builder insertParamBuilder = InsertParam.newBuilder()\n\t\t\t.withDatabaseName(this.databaseName)\n\t\t\t.withCollectionName(this.collectionName)\n\t\t\t.withFields(fields);\n\t\tif (StringUtils.hasText(this.partitionName)) {\n\t\t\tinsertParamBuilder.withPartitionName(this.partitionName);\n\t\t}\n\t\tInsertParam insertParam = insertParamBuilder.build();\n\n\t\tR<MutationResult> status = this.milvusClient.insert(insertParam);\n\t\tif (status.getException() != null) {\n\t\t\tthrow new RuntimeException(\"Failed to insert:\", status.getException());\n\t\t}\n\t}\n\n\t@Override\n\tpublic void doDelete(List<String> idList) {\n\t\tAssert.notNull(idList, \"Document id list must not be null\");\n\n\t\t// Ids are user-supplied strings that get inlined into a Milvus filter\n\t\t// expression. Delegate escaping to the same Jackson-based JSON serialization\n\t\t// used by MilvusFilterExpressionConverter so quotes, backslashes and control\n\t\t// chars cannot break out of the string literal and inject filter syntax.\n\t\tString deleteExpression = String.format(\"%s in [%s]\", this.idFieldName,\n\t\t\t\tidList.stream()\n\t\t\t\t\t.map(MilvusFilterExpressionConverter::toFilterExpressionLiteral)\n\t\t\t\t\t.collect(Collectors.joining(\",\")));\n\n\t\tDeleteParam.Builder deleteParamBuilder = DeleteParam.newBuilder()\n\t\t\t.withDatabaseName(this.databaseName)","sourceCodeStart":275,"sourceCodeEnd":311,"githubUrl":"https://github.com/spring-projects/spring-ai/blob/98a7beda4f29d80a71c5837eb4053b03a93a46f7/vector-stores/spring-ai-milvus-store/src/main/java/org/springframework/ai/vectorstore/milvus/MilvusVectorStore.java#L275-L311","documentation":"MilvusVectorStore.doAdd inserts documents via the Milvus Java SDK client. The SDK always returns an R<MutationResult> wrapper; when status.getException() is non-null the call failed on the server or transport level, and the store rethrows it as RuntimeException(\"Failed to insert:\", cause). The SDK's status message is not surfaced, so the cause must be inspected.","triggerScenarios":"Calling vectorStore.add(List<Document>) when the Milvus insert RPC fails: collection doesn't exist, embedding dimension mismatch with the collection schema, collection not loaded, connection/auth problems, or partition name doesn't exist.","commonSituations":"Embedding model dimension changed (e.g. 1536 vs 768) but Milvus collection was created with the old dimension; partitionName configured but partition absent; Milvus server restarted or unreachable; wrong collection name config.","solutions":["Inspect status exception in the stack trace (cause of this RuntimeException) for the real Milvus error code/message.","Verify the embedding model's dimension matches the collection's VECTOR field dimension; recreate the collection if not (drop and re-initialize).","Confirm the configured collection and partition names exist in Milvus (use Attu or listCollections).","Check Milvus connectivity/credentials and that the collection is loaded into memory.","Upgrade the milvus-sdk-java client version to match the server version."],"exampleFix":"// before\nEmbeddingModel model = new OpenAiEmbeddingModel(..., OpenAiEmbeddingOptions.ofModel(\"text-embedding-3-large\")); // 3072 dims, collection is 1536\n// after\n// recreate collection with matching dimension or use a 1536-dim model\ncollectionName drop; vectorStore.afterPropertiesSet(); // re-init with matching embeddingModel","handlingStrategy":"retry","validationCode":"// Pre-check dimension against the Milvus collection schema before add:\n// DescribeCollectionResponse desc = milvusClient.describeCollection(\n//     DescribeCollectionParam.newBuilder().withCollectionName(name).build());\n// assert desc.getData().getSchema() dimension == embeddingModel.dimensions()","typeGuard":null,"tryCatchPattern":"try {\n    vectorStore.add(documents);\n} catch (RuntimeException e) {\n    Throwable cause = e.getCause(); // Milvus SDK exception with real error code\n    logger.error(\"Milvus insert failed: {}\", cause == null ? e : cause.getMessage(), cause);\n    // retry with backoff for transient errors; fix schema/dimension for others\n}","preventionTips":["Match embedding model dimension to the Milvus collection schema; recreate the collection when switching models.","Verify collection and partition names exist at startup.","Health-check Milvus connectivity before batch inserts.","Keep milvus-sdk-java version compatible with the server version.","Ensure the collection is loaded before writing."],"tags":["milvus","insert","vector-store","grpc"],"backgroundTag":"database-write-failed","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"}