Error Handling

Relevant source files

The following files were used as context for generating this wiki page:

• src/proto/milvus.proto.common.rs
• src/utils.rs
• src/authentication.rs
• src/iterator.rs
• src/index/utils.rs
• tests/aggressivehpctesting/aggressivetesting.md

Error handling in the Milvus Rust SDK is designed to provide a robust bridge between the strongly-typed Rust client and the gRPC-based Milvus server responses. The system centers on converting protobuf-generated status messages into idiomatic Rust Result types, ensuring that server-side failures, rate limits, and schema mismatches are surfaced clearly to the end user.

The architecture relies on a unified Status message structure defined in the common protocol, which is validated across all service modules including Authentication, Indexing, and Data Iteration.

Core Error Architecture

The SDK utilizes a centralized utility function, status_to_result, to process the Status objects returned by the Milvus server. This function serves as the primary gatekeeper for determining if a gRPC call was successful at the application level.

The Status Structure

The server communicates the result of an operation via a Status message, which contains granular details about the failure.

Field	Type	Description
error_code	i32	(Deprecated) Legacy error enumeration.
reason	String	Human-readable explanation of the error.
code	i32	Modern error code corresponding to ErrorCode enum.
retriable	bool	Indicates if the client should attempt the operation again.
detail	String	Verbose technical details about the failure.

Sources: src/proto/milvus.proto.common.rs:4-21

Data Flow for Error Conversion

The following diagram illustrates how the SDK processes a server response and converts it into a Rust-native error state.

The SDK consistently clones the client and invokes status_to_result immediately after receiving the into_inner() response from a gRPC unary call.
Sources: src/authentication.rs:92-93, src/utils.rs

Categorized Error Handling

Authentication and Authorization Errors

The authentication module handles failures related to credential management and Role-Based Access Control (RBAC). Common errors include "User Already Exists," "Insufficient Privileges," or "Incorrect Old Password" during updates.

• Credential Operations: Functions like create_user and update_password validate the MutationResult or Status returned by the MilvusServiceClient.
• RBAC Validation: Methods such as grant_role and operate_privilege_group verify that the operation was authorized and successful before returning Ok(()).

Sources: src/authentication.rs:94-96, src/authentication.rs:590-593

Indexing and Collection Errors

Index operations often involve long-running server-side processes. The SDK implements polling logic to track these states.

• Index Creation Failures: The create_index method polls describe_index in a loop. If the IndexState transitions to Failed, a Collection(Error::IndexBuildFailed) is returned.
• Missing PK: The SDK enforces schema requirements client-side; for instance, QueryIterator returns a Schema(Error::NoPrimaryKey) if the targeted collection lacks a primary key.

Sources: src/index/utils.rs:69-74, src/iterator.rs:411-413

Iterator and Batching Errors

When dealing with large datasets via QueryIterator or SearchIterator, the SDK handles specific parameter and I/O errors.

Common Error Codes

The SDK maps server-side ErrorCode values to technical categories. Below are significant codes defined in the common protocol:

ErrorCode	Value	Significance
Success	0	The operation completed successfully.
RateLimit	49	The server is throttling requests; observed during HPC testing.
PermissionDenied	3	The user lacks the necessary RBAC role for the operation.
InsufficientMemory	52	The query node cannot load the collection due to resource constraints.
SchemaMismatch	62	The provided data does not align with the collection schema.

Sources: src/proto/milvus.proto.common.rs:168-235, tests/aggressivehpctesting/aggressivetesting.md:126-130

Testing for Robustness

High-Performance Computing (HPC) testing revealed specific error scenarios that the SDK must handle:

1. Rate Limiting: Server-side RateLimit errors (Code 49) were triggered during high-concurrency inserts, requiring custom server configuration.
2. gRPC Timeouts: Heavy loads caused client-side gRPC timeouts, leading to the implementation of timeout() methods on the ClientBuilder.
3. Silent Data Loss: In specific versions (v2.5.15), concurrent writes to multiple unique partitions resulted in bottlenecks that the SDK must monitor via final entity count verification.

Sources: tests/aggressivehpctesting/aggressivetesting.md:120-142

Summary

Error handling in the Milvus Rust SDK is a multi-layered system that transforms gRPC Status messages into actionable Rust errors. By centralizing validation in status_to_result and providing specific error context in modules like authentication and iterator, the SDK ensures that developers can handle everything from simple validation errors to complex server-side rate limiting and resource exhaustion.