Enum Error 

#[non_exhaustive]
pub enum Error {
    Connection(String),
    ConnectionClosed,
    Authentication(AuthError),
    Tls(TlsError),
    ProtocolError(ProtocolError),
    Protocol(String),
    Codec(CodecError),
    ResponseTooLarge {
        size: usize,
        limit: usize,
    },
    Type(TypeError),
    Query(String),
    Server {
        number: i32,
        class: u8,
        state: u8,
        message: String,
        server: Option<String>,
        procedure: Option<String>,
        line: u32,
    },
    Config(String),
    ConnectTimeout {
        host: String,
        port: u16,
    },
    TlsTimeout {
        host: String,
        port: u16,
    },
    LoginTimeout {
        host: String,
        port: u16,
    },
    CommandTimeout,
    Routing {
        host: String,
        port: u16,
    },
    TooManyRedirects {
        max: u8,
    },
    Io(SharedIoError),
    InvalidIdentifier(String),
    Cancel(String),
    Cancelled,
    BrowserResolution {
        instance: String,
        reason: String,
    },
    Encryption(String),
}

Errors that can occur during client operations.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

Connection(String)

Connection failed.

ConnectionClosed

Connection closed unexpectedly.

Authentication(AuthError)

Authentication failed.

Tls(TlsError)

TLS error.

ProtocolError(ProtocolError)

Protocol error from the TDS layer (preserves the source error chain).

Protocol(String)

Protocol violation with a descriptive message.

Codec(CodecError)

Codec error.

ResponseTooLarge

Response exceeded Config::max_response_size.

The response was abandoned mid-stream, so the connection is no longer usable and is discarded by the pool. Paginate, narrow the SELECT, or raise the cap.

Fields

size: usize

Bytes accumulated when the cap was exceeded.

limit: usize

The configured cap.

Type(TypeError)

Type conversion error.

Query(String)

Query execution error.

Server

Server returned an error.

Fields

number: i32

Error number.

class: u8

Error class/severity (0-25).

state: u8

Error state.

message: String

Error message.

server: Option<String>

Server name where error occurred.

procedure: Option<String>

Stored procedure name (if applicable).

line: u32

Line number in the SQL batch or procedure.

Config(String)

Configuration error.

ConnectTimeout

TCP connection timeout occurred.

Fields

host: String

Target host.

port: u16

Target port.

TlsTimeout

TLS handshake timeout occurred.

Fields

host: String

Target host.

port: u16

Target port.

LoginTimeout

Login/authentication response timeout occurred.

Fields

host: String

Target host.

port: u16

Target port.

CommandTimeout

Command execution timeout occurred.

The driver cancels the command via an Attention packet and drains the server’s acknowledgement, so the connection normally stays usable. If the server never acknowledges within a bounded wait (5 s, SqlClient parity), the connection is left mid-response and is discarded by the pool instead of being reused.

Routing

Connection routing required (Azure SQL).

Fields

host: String

Target host.

port: u16

Target port.

TooManyRedirects

Too many redirects during connection.

Fields

max: u8

Maximum redirects allowed.

Io(SharedIoError)

IO error (wrapped in Arc for Clone support).

InvalidIdentifier(String)

Invalid identifier (potential SQL injection attempt).

Cancel(String)

Query cancellation error.

Cancelled

Query was cancelled by user request.

BrowserResolution

SQL Browser service instance resolution failed.

Fields

instance: String

The instance name that was being resolved.

reason: String

Description of what went wrong.

Encryption(String)

Always Encrypted operation failed.

This error occurs during CEK decryption, column value decryption, or parameter encryption. Key material is never included in the error message.

Implementations

impl Error

pub fn is_transient(&self) -> bool

Check if this error is transient and may succeed on retry.

Transient errors include timeouts, connection issues, and certain server errors that may resolve themselves.

Per ADR-009, the following server error codes are considered transient:

• 1205: Deadlock victim
• -2: Timeout
• 10928, 10929: Resource limit (Azure)
• 40197: Service error (Azure)
• 40501: Service busy (Azure)
• 40613: Database unavailable (Azure)
• 49918, 49919, 49920: Cannot process request (Azure)
• 4060: Cannot open database (may be transient during failover)
• 18456: Login failed (may be transient in Azure during failover)

pub fn is_transient_server_error(number: i32) -> bool

Check if a server error number is transient (may succeed on retry).

This follows the error codes specified in ADR-009.

Extending with custom error codes

Applications with domain-specific transient error codes can compose this method with their own logic:

use mssql_client::Error;

fn is_transient_for_my_app(err: &Error) -> bool {
    // Check built-in transient codes first
    if err.is_transient() {
        return true;
    }
    // Add application-specific transient server errors
    if let Error::Server { number, .. } = err {
        matches!(number, 50001 | 50002) // custom app error codes
    } else {
        false
    }
}

pub fn is_terminal(&self) -> bool

Check if this is a terminal error that will never succeed on retry.

Terminal errors include syntax errors, constraint violations, and other errors that indicate programmer error or data issues.

Per ADR-009, the following server error codes are terminal:

• 102: Syntax error
• 207: Invalid column
• 208: Invalid object
• 547: Constraint violation
• 2627: Unique constraint violation
• 2601: Duplicate key

pub fn is_terminal_server_error(number: i32) -> bool

Check if a server error number is terminal (will never succeed on retry).

This follows the error codes specified in ADR-009.

pub fn is_protocol_error(&self) -> bool

Check if this error indicates a protocol/driver bug.

Protocol errors typically indicate a bug in the driver implementation rather than a user error or server issue. These are always terminal.

pub fn is_tls_error(&self) -> bool

Check if this is a TLS/encryption error.

TLS errors indicate certificate, handshake, or encryption failures. These are terminal — TLS timeouts are reported as Error::TlsTimeout instead.

pub fn is_authentication_error(&self) -> bool

Check if this is an authentication error.

pub fn is_config_error(&self) -> bool

Check if this is a configuration error.

Configuration errors are always terminal — they indicate invalid settings that cannot be resolved by retrying.

pub fn is_server_error(&self, number: i32) -> bool

Check if this is a server error with a specific number.

pub fn class(&self) -> Option<u8>

Get the error class/severity if this is a server error.

SQL Server error classes range from 0-25:

• 0-10: Informational
• 11-16: User errors
• 17-19: Resource/hardware errors
• 20-25: System errors (connection terminating)

pub fn severity(&self) -> Option<u8>

Alias for class() - returns error severity.

Trait Implementations

impl Debug for Error

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for Error

fn fmt(&self, __formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Error for Error

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl From<AuthError> for Error

fn from(source: AuthError) -> Self

Converts to this type from the input type.

impl From<CodecError> for Error

fn from(e: CodecError) -> Self

Converts to this type from the input type.

impl From<EncryptionError> for Error

Available on crate feature always-encrypted only.

fn from(e: EncryptionError) -> Self

Converts to this type from the input type.

impl From<Error> for Error

fn from(e: Error) -> Self

Converts to this type from the input type.

impl From<ProtocolError> for Error

fn from(source: ProtocolError) -> Self

Converts to this type from the input type.

impl From<TlsError> for Error

fn from(source: TlsError) -> Self

Converts to this type from the input type.

impl From<TypeError> for Error

fn from(source: TypeError) -> Self

Converts to this type from the input type.