llama_cpp_bindings/
error.rs

1use std::ffi::NulError;
2use std::num::NonZeroI32;
3use std::os::raw::c_int;
4use std::path::PathBuf;
5use std::string::FromUtf8Error;
6
7use crate::llama_batch::BatchAddError;
8
9/// A failable result from a llama.cpp function.
10pub type Result<TValue> = std::result::Result<TValue, LlamaCppError>;
11
12/// All errors that can occur in the llama-cpp crate.
13#[derive(Debug, Eq, PartialEq, thiserror::Error)]
14pub enum LlamaCppError {
15    /// The backend was already initialized. This can generally be ignored as initializing the backend
16    /// is idempotent.
17    #[error("BackendAlreadyInitialized")]
18    BackendAlreadyInitialized,
19    /// There was an error while get the chat template from model.
20    #[error("{0}")]
21    ChatTemplateError(#[from] ChatTemplateError),
22    /// There was an error while decoding a batch.
23    #[error("{0}")]
24    DecodeError(#[from] DecodeError),
25    /// There was an error while encoding a batch.
26    #[error("{0}")]
27    EncodeError(#[from] EncodeError),
28    /// There was an error loading a model.
29    #[error("{0}")]
30    LlamaModelLoadError(#[from] LlamaModelLoadError),
31    /// There was an error creating a new model context.
32    #[error("{0}")]
33    LlamaContextLoadError(#[from] LlamaContextLoadError),
34    /// There was an error adding a token to a batch.
35    #[error["{0}"]]
36    BatchAddError(#[from] BatchAddError),
37    /// see [`EmbeddingsError`]
38    #[error(transparent)]
39    EmbeddingError(#[from] EmbeddingsError),
40    // See [`LlamaSamplerError`]
41    /// Backend device not found
42    #[error("Backend device {0} not found")]
43    BackendDeviceNotFound(usize),
44    /// Max devices exceeded
45    #[error("Max devices exceeded. Max devices is {0}")]
46    MaxDevicesExceeded(usize),
47    /// Failed to convert JSON schema to grammar.
48    #[error("JsonSchemaToGrammarError: {0}")]
49    JsonSchemaToGrammarError(String),
50}
51
52/// There was an error while getting the chat template from a model.
53#[derive(Debug, Eq, PartialEq, thiserror::Error)]
54pub enum ChatTemplateError {
55    /// gguf has no chat template (by that name)
56    #[error("chat template not found - returned null pointer")]
57    MissingTemplate,
58
59    /// chat template contained a null byte
60    #[error("null byte in string {0}")]
61    NullError(#[from] NulError),
62
63    /// The chat template was not valid utf8.
64    #[error(transparent)]
65    Utf8Error(#[from] std::str::Utf8Error),
66}
67
68/// Failed fetching metadata value
69#[derive(Debug, Eq, PartialEq, thiserror::Error)]
70pub enum MetaValError {
71    /// The provided string contains an unexpected null-byte
72    #[error("null byte in string {0}")]
73    NullError(#[from] NulError),
74
75    /// The returned data contains invalid UTF8 data
76    #[error("FromUtf8Error {0}")]
77    FromUtf8Error(#[from] FromUtf8Error),
78
79    /// Got negative return value. This happens if the key or index queried does not exist.
80    #[error("Negative return value. Likely due to a missing index or key. Got return value: {0}")]
81    NegativeReturn(i32),
82}
83
84/// Failed to Load context
85#[derive(Debug, Eq, PartialEq, thiserror::Error)]
86pub enum LlamaContextLoadError {
87    /// llama.cpp returned null
88    #[error("null reference from llama.cpp")]
89    NullReturn,
90}
91
92/// Failed to decode a batch.
93#[derive(Debug, Eq, PartialEq, thiserror::Error)]
94pub enum DecodeError {
95    /// No kv cache slot was available.
96    #[error("Decode Error 1: NoKvCacheSlot")]
97    NoKvCacheSlot,
98    /// The number of tokens in the batch was 0.
99    #[error("Decode Error -1: n_tokens == 0")]
100    NTokensZero,
101    /// An unknown error occurred.
102    #[error("Decode Error {0}: unknown")]
103    Unknown(c_int),
104}
105
106/// Failed to decode a batch.
107#[derive(Debug, Eq, PartialEq, thiserror::Error)]
108pub enum EncodeError {
109    /// No kv cache slot was available.
110    #[error("Encode Error 1: NoKvCacheSlot")]
111    NoKvCacheSlot,
112    /// The number of tokens in the batch was 0.
113    #[error("Encode Error -1: n_tokens == 0")]
114    NTokensZero,
115    /// An unknown error occurred.
116    #[error("Encode Error {0}: unknown")]
117    Unknown(c_int),
118}
119
120/// When embedding related functions fail
121#[derive(Debug, Eq, PartialEq, thiserror::Error)]
122pub enum EmbeddingsError {
123    /// Embeddings weren't enabled in the context options
124    #[error("Embeddings weren't enabled in the context options")]
125    NotEnabled,
126    /// Logits weren't enabled for the given token
127    #[error("Logits were not enabled for the given token")]
128    LogitsNotEnabled,
129    /// The given sequence index exceeds the max sequence id
130    #[error("Can't use sequence embeddings with a model supporting only LLAMA_POOLING_TYPE_NONE")]
131    NonePoolType,
132    /// The embedding dimension does not fit into a usize.
133    #[error("Invalid embedding dimension: {0}")]
134    InvalidEmbeddingDimension(#[source] std::num::TryFromIntError),
135}
136
137/// When logits-related functions fail
138#[derive(Debug, Eq, PartialEq, thiserror::Error)]
139pub enum LogitsError {
140    /// The logits data pointer is null.
141    #[error("logits data pointer is null")]
142    NullLogits,
143    /// The requested token index has not been initialized for logits.
144    #[error("logit for token index {0} is not initialized")]
145    TokenNotInitialized(i32),
146    /// The token index exceeds the context size.
147    #[error("token index {token_index} exceeds context size {context_size}")]
148    TokenIndexExceedsContext {
149        /// The token index that was requested.
150        token_index: u32,
151        /// The context size.
152        context_size: u32,
153    },
154    /// The vocabulary size does not fit into a usize.
155    #[error("n_vocab does not fit into usize: {0}")]
156    VocabSizeOverflow(#[source] std::num::TryFromIntError),
157    /// The token index does not fit into a u32.
158    #[error("token_index does not fit into u32: {0}")]
159    TokenIndexOverflow(#[source] std::num::TryFromIntError),
160}
161
162/// Errors that can occur when initializing a grammar sampler
163#[derive(Debug, Eq, PartialEq, thiserror::Error)]
164pub enum GrammarError {
165    /// The grammar root was not found in the grammar string
166    #[error("Grammar root not found in grammar string")]
167    RootNotFound,
168    /// The trigger word contains null bytes
169    #[error("Trigger word contains null bytes: {0}")]
170    TriggerWordNullBytes(NulError),
171    /// The grammar string or root contains null bytes
172    #[error("Grammar string or root contains null bytes: {0}")]
173    GrammarNullBytes(NulError),
174    /// A string contains null bytes
175    #[error("String contains null bytes: {0}")]
176    NulError(#[from] NulError),
177    /// The grammar call returned null
178    #[error("Grammar initialization failed: {0}")]
179    NullGrammar(String),
180    /// An integer value exceeded the allowed range
181    #[error("Integer overflow: {0}")]
182    IntegerOverflow(String),
183    /// An error from the llguidance library
184    #[error("llguidance error: {0}")]
185    LlguidanceError(String),
186}
187
188/// Errors that can occur when creating a sampling configuration.
189#[derive(Debug, Eq, PartialEq, thiserror::Error)]
190pub enum SamplingError {
191    /// An integer value exceeded the allowed range
192    #[error("Integer overflow: {0}")]
193    IntegerOverflow(String),
194}
195
196/// Errors that can occur when sampling a token.
197#[derive(Debug, Eq, PartialEq, thiserror::Error)]
198pub enum SampleError {
199    /// A C++ exception was thrown during sampling
200    #[error("C++ exception during sampling: {0}")]
201    CppException(String),
202
203    /// An invalid argument was passed to the sampler
204    #[error("Invalid argument passed to sampler")]
205    InvalidArgument,
206}
207
208/// Decode a error from llama.cpp into a [`DecodeError`].
209impl From<NonZeroI32> for DecodeError {
210    fn from(value: NonZeroI32) -> Self {
211        match value.get() {
212            1 => Self::NoKvCacheSlot,
213            -1 => Self::NTokensZero,
214            error_code => Self::Unknown(error_code),
215        }
216    }
217}
218
219/// Encode a error from llama.cpp into a [`EncodeError`].
220impl From<NonZeroI32> for EncodeError {
221    fn from(value: NonZeroI32) -> Self {
222        match value.get() {
223            1 => Self::NoKvCacheSlot,
224            -1 => Self::NTokensZero,
225            error_code => Self::Unknown(error_code),
226        }
227    }
228}
229
230/// An error that can occur when loading a model.
231#[derive(Debug, Eq, PartialEq, thiserror::Error)]
232pub enum LlamaModelLoadError {
233    /// There was a null byte in a provided string and thus it could not be converted to a C string.
234    #[error("null byte in string {0}")]
235    NullError(#[from] NulError),
236    /// llama.cpp returned a nullptr - this could be many different causes.
237    #[error("null result from llama cpp")]
238    NullResult,
239    /// Failed to convert the path to a rust str. This means the path was not valid unicode
240    #[error("failed to convert path {0} to str")]
241    PathToStrError(PathBuf),
242    /// The model file does not exist at the given path.
243    #[error("model file not found: {0}")]
244    FileNotFound(PathBuf),
245}
246
247/// An error that can occur when loading a model.
248#[derive(Debug, Eq, PartialEq, thiserror::Error)]
249pub enum LlamaLoraAdapterInitError {
250    /// There was a null byte in a provided string and thus it could not be converted to a C string.
251    #[error("null byte in string {0}")]
252    NullError(#[from] NulError),
253    /// llama.cpp returned a nullptr - this could be many different causes.
254    #[error("null result from llama cpp")]
255    NullResult,
256    /// Failed to convert the path to a rust str. This means the path was not valid unicode
257    #[error("failed to convert path {0} to str")]
258    PathToStrError(PathBuf),
259    /// The adapter file does not exist at the given path.
260    #[error("adapter file not found: {0}")]
261    FileNotFound(PathBuf),
262}
263
264/// An error that can occur when loading a model.
265#[derive(Debug, Eq, PartialEq, thiserror::Error)]
266pub enum LlamaLoraAdapterSetError {
267    /// llama.cpp returned a non-zero error code.
268    #[error("error code from llama cpp")]
269    ErrorResult(i32),
270}
271
272/// An error that can occur when loading a model.
273#[derive(Debug, Eq, PartialEq, thiserror::Error)]
274pub enum LlamaLoraAdapterRemoveError {
275    /// llama.cpp returned a non-zero error code.
276    #[error("error code from llama cpp")]
277    ErrorResult(i32),
278}
279
280/// An error that can occur when converting a token to a string.
281#[derive(Debug, thiserror::Error, Clone)]
282#[non_exhaustive]
283pub enum TokenToStringError {
284    /// the token type was unknown
285    #[error("Unknown Token Type")]
286    UnknownTokenType,
287    /// There was insufficient buffer space to convert the token to a string.
288    #[error("Insufficient Buffer Space {0}")]
289    InsufficientBufferSpace(c_int),
290    /// The token was not valid utf8.
291    #[error("FromUtf8Error {0}")]
292    FromUtf8Error(#[from] FromUtf8Error),
293    /// An integer conversion failed.
294    #[error("Integer conversion error: {0}")]
295    IntConversionError(#[from] std::num::TryFromIntError),
296}
297
298/// Failed to convert a string to a token sequence.
299#[derive(Debug, thiserror::Error)]
300pub enum StringToTokenError {
301    /// the string contained a null byte and thus could not be converted to a c string.
302    #[error("{0}")]
303    NulError(#[from] NulError),
304    #[error("{0}")]
305    /// Failed to convert a provided integer to a [`c_int`].
306    CIntConversionError(#[from] std::num::TryFromIntError),
307}
308
309/// Failed to apply model chat template.
310#[derive(Debug, thiserror::Error)]
311pub enum NewLlamaChatMessageError {
312    /// the string contained a null byte and thus could not be converted to a c string.
313    #[error("{0}")]
314    NulError(#[from] NulError),
315}
316
317/// Failed to apply model chat template.
318#[derive(Debug, thiserror::Error)]
319pub enum ApplyChatTemplateError {
320    /// the string contained a null byte and thus could not be converted to a c string.
321    #[error("{0}")]
322    NulError(#[from] NulError),
323    /// the string could not be converted to utf8.
324    #[error("{0}")]
325    FromUtf8Error(#[from] FromUtf8Error),
326    /// llama.cpp returned a null pointer for the template result.
327    #[error("null result from llama.cpp")]
328    NullResult,
329    /// llama.cpp returned an error code.
330    #[error("ffi error {0}")]
331    FfiError(i32),
332    /// invalid grammar trigger data returned by llama.cpp.
333    #[error("invalid grammar trigger data")]
334    InvalidGrammarTriggerType,
335    /// An integer conversion failed.
336    #[error("Integer conversion error: {0}")]
337    IntConversionError(#[from] std::num::TryFromIntError),
338}
339
340/// Failed to parse a chat response.
341#[derive(Debug, thiserror::Error)]
342pub enum ChatParseError {
343    /// the string contained a null byte and thus could not be converted to a c string.
344    #[error("{0}")]
345    NulError(#[from] NulError),
346    /// the string could not be converted to utf8.
347    #[error("{0}")]
348    Utf8Error(#[from] FromUtf8Error),
349    /// llama.cpp returned a null pointer for the parse result.
350    #[error("null result from llama.cpp")]
351    NullResult,
352    /// llama.cpp returned an error code.
353    #[error("ffi error {0}")]
354    FfiError(i32),
355}
356
357/// Failed to accept a token in a sampler.
358#[derive(Debug, thiserror::Error)]
359pub enum SamplerAcceptError {
360    /// A C++ exception was thrown during accept
361    #[error("C++ exception during sampler accept: {0}")]
362    CppException(String),
363
364    /// An invalid argument was passed (null sampler or null error pointer)
365    #[error("Invalid argument passed to sampler accept")]
366    InvalidArgument,
367}
368
369/// Errors that can occur when modifying model parameters.
370#[derive(Debug, Eq, PartialEq, thiserror::Error)]
371pub enum ModelParamsError {
372    /// The internal override vector has no available slot.
373    #[error("No available slot in override vector")]
374    NoAvailableSlot,
375    /// The first override slot is not empty.
376    #[error("Override slot is not empty")]
377    SlotNotEmpty,
378    /// A character in the key is not a valid C char.
379    #[error("Invalid character in key: byte {byte}, {reason}")]
380    InvalidCharacterInKey {
381        /// The byte value that failed conversion.
382        byte: u8,
383        /// The reason the conversion failed.
384        reason: String,
385    },
386}
387
388/// Failed to sample a token from the data array.
389#[derive(Debug, Eq, PartialEq, thiserror::Error)]
390pub enum TokenSamplingError {
391    /// The sampler did not select any token.
392    #[error("No token was selected by the sampler")]
393    NoTokenSelected,
394}
395
396#[cfg(test)]
397mod tests {
398    use std::num::NonZeroI32;
399
400    use super::{DecodeError, EncodeError};
401
402    #[test]
403    fn decode_error_no_kv_cache_slot() {
404        let error = DecodeError::from(NonZeroI32::new(1).expect("1 is non-zero"));
405
406        assert_eq!(error, DecodeError::NoKvCacheSlot);
407        assert_eq!(error.to_string(), "Decode Error 1: NoKvCacheSlot");
408    }
409
410    #[test]
411    fn decode_error_n_tokens_zero() {
412        let error = DecodeError::from(NonZeroI32::new(-1).expect("-1 is non-zero"));
413
414        assert_eq!(error, DecodeError::NTokensZero);
415        assert_eq!(error.to_string(), "Decode Error -1: n_tokens == 0");
416    }
417
418    #[test]
419    fn decode_error_unknown() {
420        let error = DecodeError::from(NonZeroI32::new(42).expect("42 is non-zero"));
421
422        assert_eq!(error, DecodeError::Unknown(42));
423        assert_eq!(error.to_string(), "Decode Error 42: unknown");
424    }
425
426    #[test]
427    fn encode_error_no_kv_cache_slot() {
428        let error = EncodeError::from(NonZeroI32::new(1).expect("1 is non-zero"));
429
430        assert_eq!(error, EncodeError::NoKvCacheSlot);
431        assert_eq!(error.to_string(), "Encode Error 1: NoKvCacheSlot");
432    }
433
434    #[test]
435    fn encode_error_n_tokens_zero() {
436        let error = EncodeError::from(NonZeroI32::new(-1).expect("-1 is non-zero"));
437
438        assert_eq!(error, EncodeError::NTokensZero);
439        assert_eq!(error.to_string(), "Encode Error -1: n_tokens == 0");
440    }
441
442    #[test]
443    fn encode_error_unknown() {
444        let error = EncodeError::from(NonZeroI32::new(99).expect("99 is non-zero"));
445
446        assert_eq!(error, EncodeError::Unknown(99));
447        assert_eq!(error.to_string(), "Encode Error 99: unknown");
448    }
449}
llama_cpp_bindings/error.rs

llama_cpp_bindings/
error.rs
