Struct Error 

#[non_exhaustive]
pub struct Error { /* private fields */ }

The error type returned by Toasty operations. The error type used throughout Toasty.

Error is a thin wrapper around an Arc, making it cheap to clone. Errors form a chain: each error can optionally carry a cause that provides additional context. When displayed, the chain is printed from outermost context to innermost root cause, separated by : .

Construct errors through the associated functions on this type (e.g., Error::record_not_found, Error::from_args).

Examples

use toasty_core::Error;

// Create an ad-hoc error
let err = Error::from_args(format_args!("something went wrong"));
assert_eq!(err.to_string(), "something went wrong");

// Wrap it with additional context
let wrapped = err.context(Error::from_args(format_args!("while loading user")));
assert_eq!(wrapped.to_string(), "while loading user: something went wrong");

Implementations

impl Error

pub fn from_args<'a>(message: Arguments<'a>) -> Error

Creates an error from a format string.

Examples

use toasty_core::Error;

let err = Error::from_args(format_args!("value {} is invalid", "foo"));

pub fn is_adhoc(&self) -> bool

Returns true if this error is an adhoc error.

Examples

use toasty_core::Error;

let err = Error::from_args(format_args!("oops"));
assert!(err.is_adhoc());

let err = Error::record_not_found("missing");
assert!(!err.is_adhoc());

impl Error

pub fn condition_failed(context: impl Into<String>) -> Error

Creates a condition failed error.

This is used when a conditional operation’s condition evaluates to false, such as:

• An UPDATE with a WHERE clause that matches no rows
• A DynamoDB conditional write that fails
• An optimistic lock version check that fails

The context parameter provides information about what condition failed.

Examples

use toasty_core::Error;

let err = Error::condition_failed("optimistic lock version mismatch");
assert!(err.is_condition_failed());
assert_eq!(err.to_string(), "condition failed: optimistic lock version mismatch");

pub fn is_condition_failed(&self) -> bool

Returns true if this error is a condition failed error.

impl Error

pub fn connection_pool(err: impl Error + Send + Sync + 'static) -> Error

Creates an error from a connection pool error.

This is used for errors that occur when managing the connection pool (e.g., deadpool errors).

Examples

use toasty_core::Error;

let io_err = std::io::Error::new(std::io::ErrorKind::TimedOut, "pool exhausted");
let err = Error::connection_pool(io_err);
assert!(err.is_connection_pool());

pub fn is_connection_pool(&self) -> bool

Returns true if this error is a connection pool error.

impl Error

pub fn driver_operation_failed(err: impl Error + Send + Sync + 'static) -> Error

Creates an error from a driver operation failure.

This is the preferred way to convert driver-specific errors (rusqlite, tokio-postgres, mysql_async, AWS SDK errors, etc.) into toasty errors.

Examples

use toasty_core::Error;

let io_err = std::io::Error::new(std::io::ErrorKind::ConnectionRefused, "refused");
let err = Error::driver_operation_failed(io_err);
assert!(err.is_driver_operation_failed());

pub fn is_driver_operation_failed(&self) -> bool

Returns true if this error is a driver operation failure.

impl Error

pub fn expression_evaluation_failed(message: impl Into<String>) -> Error

Creates an expression evaluation failed error.

This is used when expression evaluation fails at runtime due to:

• Missing context or data
• Type mismatches
• Non-evaluable constructs

Examples

use toasty_core::Error;

let err = Error::expression_evaluation_failed("unresolved reference");
assert!(err.is_expression_evaluation_failed());

pub fn is_expression_evaluation_failed(&self) -> bool

Returns true if this error is an expression evaluation failure.

impl Error

pub fn invalid_connection_url(message: impl Into<String>) -> Error

Creates an invalid connection URL error.

Examples

use toasty_core::Error;

let err = Error::invalid_connection_url("missing host in connection string");
assert!(err.is_invalid_connection_url());
assert_eq!(
    err.to_string(),
    "invalid connection URL: missing host in connection string"
);

pub fn is_invalid_connection_url(&self) -> bool

Returns true if this error is an invalid connection URL error.

impl Error

pub fn invalid_driver_configuration(message: impl Into<String>) -> Error

Creates an invalid driver configuration error.

This is used when a driver’s capability configuration is invalid or inconsistent. These errors indicate a bug in the driver implementation.

Examples

use toasty_core::Error;

let err = Error::invalid_driver_configuration("inconsistent capability flags");
assert!(err.is_invalid_driver_configuration());

pub fn is_invalid_driver_configuration(&self) -> bool

Returns true if this error is an invalid driver configuration error.

impl Error

pub fn invalid_record_count(context: impl Into<String>) -> Error

Creates an invalid record count error.

This is used when an operation expects exactly one record but finds multiple.

The context parameter provides information about the operation.

Examples

use toasty_core::Error;

let err = Error::invalid_record_count("expected 1 record, found 3");
assert!(err.is_invalid_record_count());
assert_eq!(err.to_string(), "invalid record count: expected 1 record, found 3");

pub fn is_invalid_record_count(&self) -> bool

Returns true if this error is an invalid record count error.

impl Error

pub fn invalid_result(message: impl Into<String>) -> Error

Creates an invalid result error.

This is used when a query result has an unexpected structure - the database returned valid data, but its shape doesn’t match what the operation expected.

Examples

use toasty_core::Error;

let err = Error::invalid_result("expected Stream, got Count");
assert!(err.is_invalid_result());
assert_eq!(err.to_string(), "invalid result: expected Stream, got Count");

pub fn is_invalid_result(&self) -> bool

Returns true if this error is an invalid result error.

impl Error

pub fn invalid_schema(message: impl Into<String>) -> Error

Creates an invalid schema error.

This is used when a schema definition is invalid - duplicate names, invalid column configurations, incompatible features, etc. These errors are typically caught at build/migration time.

Examples

use toasty_core::Error;

let err = Error::invalid_schema("duplicate index name `idx_users`");
assert!(err.is_invalid_schema());
assert_eq!(err.to_string(), "invalid schema: duplicate index name `idx_users`");

pub fn is_invalid_schema(&self) -> bool

Returns true if this error is an invalid schema error.

impl Error

pub fn invalid_statement(message: impl Into<String>) -> Error

Creates an invalid statement error.

This is used when a statement is malformed or references invalid schema elements. These errors occur during statement lowering/execution at runtime.

Examples

use toasty_core::Error;

let err = Error::invalid_statement("field `foo` does not exist");
assert!(err.is_invalid_statement());
assert_eq!(err.to_string(), "invalid statement: field `foo` does not exist");

pub fn is_invalid_statement(&self) -> bool

Returns true if this error is an invalid statement error.

impl Error

pub fn type_conversion(value: Value, to_type: &'static str) -> Error

Creates a type conversion error.

This is used when a value cannot be converted to the expected type.

Examples

use toasty_core::Error;
use toasty_core::stmt::Value;

let err = Error::type_conversion(Value::I64(42), "String");
assert!(err.is_type_conversion());
assert_eq!(err.to_string(), "cannot convert I64 to String");

pub fn is_type_conversion(&self) -> bool

Returns true if this error is a type conversion error.

impl Error

pub fn read_only_transaction(message: impl Into<String>) -> Error

Creates a read-only transaction error.

Returned when a write operation is attempted inside a read-only transaction (e.g. PostgreSQL SQLSTATE 25006, MySQL error 1792).

Examples

use toasty_core::Error;

let err = Error::read_only_transaction("INSERT not allowed");
assert!(err.is_read_only_transaction());
assert_eq!(
    err.to_string(),
    "read-only transaction: INSERT not allowed"
);

pub fn is_read_only_transaction(&self) -> bool

Returns true if this error is a read-only transaction error.

impl Error

pub fn record_not_found(context: impl Into<String>) -> Error

Creates a record not found error.

This is the root cause error when a record lookup (by query or key) returns no results.

The context parameter provides immediate context about what was not found. Additional context can be added at each layer via .context().

Examples

use toasty_core::Error;

// With context describing what wasn't found (string literal)
let err = Error::record_not_found("table=users key={id: 123}");
assert_eq!(err.to_string(), "record not found: table=users key={id: 123}");

// With context from format! or String
let table = "users";
let key = 123;
let err = Error::record_not_found(format!("table={} key={}", table, key));
assert_eq!(err.to_string(), "record not found: table=users key=123");

pub fn is_record_not_found(&self) -> bool

Returns true if this error is a record not found error.

impl Error

pub fn serialization_failure(message: impl Into<String>) -> Error

Creates a serialization failure error.

Returned when the database aborts a transaction due to a serialization conflict (e.g. PostgreSQL SQLSTATE 40001, MySQL error 1213).

Examples

use toasty_core::Error;

let err = Error::serialization_failure("concurrent update conflict");
assert!(err.is_serialization_failure());

pub fn is_serialization_failure(&self) -> bool

Returns true if this error is a serialization failure.

impl Error

pub fn transaction_timeout(duration: Duration) -> Error

Creates a transaction timeout error.

Returned when the transaction closure exceeds the configured timeout. The transaction is automatically rolled back.

Examples

use std::time::Duration;
use toasty_core::Error;

let err = Error::transaction_timeout(Duration::from_secs(30));
assert!(err.is_transaction_timeout());

pub fn is_transaction_timeout(&self) -> bool

Returns true if this error is a transaction timeout.

impl Error

pub fn unsupported_feature(message: impl Into<String>) -> Error

Creates an unsupported feature error.

This is used when a database does not support a requested feature, such as a specific type, storage constraint, or capability.

Examples

use toasty_core::Error;

let err = Error::unsupported_feature("ARRAY type not supported");
assert!(err.is_unsupported_feature());
assert_eq!(err.to_string(), "unsupported feature: ARRAY type not supported");

pub fn is_unsupported_feature(&self) -> bool

Returns true if this error is an unsupported feature error.

impl Error

pub fn validation_failed(message: impl Into<String>) -> Error

Creates a general validation error with a custom message.

Examples

use toasty_core::Error;

let err = Error::validation_failed("email format invalid");
assert!(err.is_validation());
assert_eq!(err.to_string(), "validation failed: email format invalid");

pub fn validation_length( value_len: usize, min: Option<usize>, max: Option<usize>, ) -> Error

Creates a validation error for a length constraint violation.

This is used when a string value violates minimum or maximum length constraints.

Examples

use toasty_core::Error;

// Value too short
let err = Error::validation_length(2, Some(5), Some(100));
assert_eq!(err.to_string(), "value length 2 is too short (minimum: 5)");

// Value too long
let err = Error::validation_length(150, Some(5), Some(100));
assert_eq!(err.to_string(), "value length 150 is too long (maximum: 100)");

pub fn is_validation(&self) -> bool

Returns true if this error is a validation error.

impl Error

pub fn context(self, consequent: impl IntoError) -> Error

Wraps this error with additional context.

The consequent becomes the new outermost error and self becomes its cause. When displayed, the chain reads from outermost to innermost:

consequent: self

Panics

Panics if consequent already has a cause attached.

Examples

use toasty_core::Error;

let root = Error::from_args(format_args!("disk full"));
let err = root.context(Error::from_args(format_args!("failed to save")));
assert_eq!(err.to_string(), "failed to save: disk full");

Trait Implementations

impl Clone for Error

fn clone(&self) -> Error

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

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, f: &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.