nemo_flow/
error.rs

1// SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2// SPDX-License-Identifier: Apache-2.0
3
4//! Error types for the NeMo Flow runtime.
5//!
6//! All fallible operations in the runtime return [`Result<T>`], which uses
7//! [`FlowError`] as the error type. Errors are categorized by cause
8//! (duplicate registration, missing entity, guardrail rejection, etc.).
9
10use thiserror::Error;
11
12/// The error type for all NeMo Flow runtime operations.
13///
14/// Each variant represents a distinct failure mode that callers can match on
15/// to determine the appropriate recovery strategy.
16#[derive(Debug, Error)]
17pub enum FlowError {
18    /// A resource with the given name is already registered.
19    ///
20    /// Returned when attempting to register a guardrail, intercept, or subscriber
21    /// with a name that is already in use. Deregister the existing entry first,
22    /// or choose a different name.
23    #[error("already exists: {0}")]
24    AlreadyExists(String),
25
26    /// The requested resource was not found.
27    ///
28    /// Returned when attempting to remove a scope handle by UUID that does not
29    /// exist in the scope stack, or when looking up a non-existent entity.
30    #[error("not found: {0}")]
31    NotFound(String),
32
33    /// A function argument was invalid for the requested operation.
34    ///
35    /// Returned when a provided value is well-formed but violates an API
36    /// precondition, such as attempting to pop a scope that is not currently
37    /// at the top of the stack.
38    #[error("invalid argument: {0}")]
39    InvalidArgument(String),
40
41    /// The scope stack is empty.
42    ///
43    /// This should not occur under normal operation because the root scope is
44    /// always present and cannot be removed.
45    #[error("scope stack empty")]
46    ScopeStackEmpty,
47
48    /// A conditional execution guardrail rejected the operation.
49    ///
50    /// The contained string is the rejection reason provided by the guardrail.
51    /// This is returned during `tool_call_execute` or `llm_call_execute` when
52    /// a conditional guardrail returns `Some(reason)`.
53    #[error("guardrail rejected: {0}")]
54    GuardrailRejected(String),
55
56    /// An internal runtime error (e.g., lock poisoning).
57    #[error("internal error: {0}")]
58    Internal(String),
59}
60
61/// A specialized [`Result`](std::result::Result) type for NeMo Flow operations.
62pub type Result<T> = std::result::Result<T, FlowError>;
63
64#[cfg(test)]
65#[path = "../tests/coverage/error_tests.rs"]
66mod tests;
nemo_flow/error.rs

nemo_flow/
error.rs
