Skip to main content

rusttorch_core/
error.rs

1//! Errors returned by the fallible RustTorch API.
2
3use std::path::PathBuf;
4
5use tch::{Device, Kind};
6
7/// Result type used by RustTorch APIs that can fail recoverably.
8pub type Result<T> = std::result::Result<T, RustTorchError>;
9
10/// Recoverable configuration, graph, state, and backend failures.
11///
12/// New variants may be added in future releases, so downstream matches must
13/// include a wildcard arm.
14#[derive(Debug, thiserror::Error)]
15#[non_exhaustive]
16pub enum RustTorchError {
17    /// A named configuration field has an invalid value.
18    #[error("invalid configuration for {field}: {reason}")]
19    InvalidConfiguration {
20        /// Configuration field that failed validation.
21        field: &'static str,
22        /// Human-readable validation failure.
23        reason: String,
24    },
25
26    /// Tensor dimensions do not satisfy an operation's contract.
27    #[error("invalid dimensions for {context}: expected {expected}, got {actual}")]
28    InvalidDimensions {
29        /// Operation or value being validated.
30        context: String,
31        /// Required dimensions or rank.
32        expected: String,
33        /// Dimensions or rank that were supplied.
34        actual: String,
35    },
36
37    /// A requested compatibility option is not implemented by the backend.
38    #[error("{component} does not support option `{option}` in the MVP")]
39    UnsupportedOption {
40        /// Component that rejected the option.
41        component: &'static str,
42        /// Unsupported option name.
43        option: &'static str,
44    },
45
46    /// An explicitly requested execution backend cannot be used.
47    #[error("{backend} backend is unavailable: {reason}")]
48    BackendUnavailable {
49        /// Backend name.
50        backend: &'static str,
51        /// Reason the backend cannot be used.
52        reason: String,
53    },
54
55    /// A tensor is located on a different device than required.
56    #[error("device mismatch in {context}: expected {expected:?}, got {actual:?}")]
57    DeviceMismatch {
58        /// Operation or value being validated.
59        context: String,
60        /// Required tensor device.
61        expected: Device,
62        /// Actual tensor device.
63        actual: Device,
64    },
65
66    /// A state tensor's shape differs from the model tensor's shape.
67    #[error("shape mismatch for `{name}`: expected {expected:?}, got {actual:?}")]
68    ShapeMismatch {
69        /// Destination state key.
70        name: String,
71        /// Shape required by the model.
72        expected: Vec<i64>,
73        /// Shape found in the input state.
74        actual: Vec<i64>,
75    },
76
77    /// A state tensor's dtype differs from the model tensor's dtype.
78    #[error("dtype mismatch for `{name}`: expected {expected:?}, got {actual:?}")]
79    DtypeMismatch {
80        /// Destination state key.
81        name: String,
82        /// Dtype required by the model.
83        expected: Kind,
84        /// Dtype found in the input state.
85        actual: Kind,
86    },
87
88    /// Strict state loading found missing or unexpected keys.
89    #[error("incompatible model state; missing={missing:?}, unexpected={unexpected:?}")]
90    IncompatibleModelState {
91        /// Model keys absent from the input state.
92        missing: Vec<String>,
93        /// Input keys that do not map to model state.
94        unexpected: Vec<String>,
95    },
96
97    /// Multiple source keys map to the same destination key.
98    #[error("duplicate state mapping target `{0}`")]
99    DuplicateMappedKey(String),
100
101    /// A graph or input collection contains the same name more than once.
102    #[error("duplicate name `{0}`")]
103    DuplicateName(String),
104
105    /// A required named graph input was not provided.
106    #[error("missing graph input `{0}`")]
107    MissingGraphInput(String),
108
109    /// A graph input was provided but is not declared by the graph.
110    #[error("unexpected graph input `{0}`")]
111    UnexpectedGraphInput(String),
112
113    /// A requested named graph output does not exist.
114    #[error("missing graph output `{0}`")]
115    MissingGraphOutput(String),
116
117    /// A graph violates structural or tensor-spec constraints.
118    #[error("graph validation failed: {0}")]
119    GraphValidation(String),
120
121    /// A graph operation cannot be executed by the selected executor.
122    #[error("unsupported graph operation: {0}")]
123    UnsupportedGraphOperation(String),
124
125    /// A model file format is not supported by the state APIs.
126    #[error("unsupported model file `{path}`: {reason}")]
127    UnsupportedModelFile {
128        /// Rejected file path.
129        path: PathBuf,
130        /// Required format or rejection reason.
131        reason: String,
132    },
133
134    /// An error returned by `tch` or LibTorch.
135    #[error(transparent)]
136    Backend(#[from] tch::TchError),
137}