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}