Enum LlmBackendError 

#[non_exhaustive]
pub enum LlmBackendError {
    NonZeroExit {
        exit_code: Option<i32>,
        signal: Option<i32>,
        stdout_tail: String,
        stderr_tail: String,
        binary: String,
        hint: String,
    },
    SpawnFailed {
        binary: String,
        source: String,
    },
    Timeout {
        secs: u64,
        binary: String,
    },
    NoBackendsAvailable,
}

Structured error for an LLM subprocess invocation that failed.

Each variant carries the information needed to diagnose the failure WITHOUT re-running the subprocess: the binary, the exit code, and a truncated tail of stdout/stderr so the operator can see WHY the call failed (rate limit, OAuth, OOM, segfault, missing binary, …).

Distinct from AppError::Embedding(String) (the legacy v1.0.81 shape) so the call sites can match on the failure category programmatically instead of parsing the message string. The Display impl preserves the legacy string format for back-compat with tracing consumers and the i18n layer.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

NonZeroExit

Subprocess exited with a non-zero status. The hint is looked up from EXIT_CODE_HINTS and tells the operator what to do next (re-auth, reduce parallelism, report upstream, etc.).

Fields

exit_code: Option<i32>

Process exit code (None if killed by a signal).

signal: Option<i32>

Unix signal that killed the process (2 = SIGINT, 15 = SIGTERM, 9 = SIGKILL). None when the process exited normally.

stdout_tail: String

Last 1 KiB of the subprocess stdout, UTF-8 lossy-decoded.

stderr_tail: String

Last 1 KiB of the subprocess stderr, UTF-8 lossy-decoded.

binary: String

Path of the binary that was spawned (e.g. /usr/bin/codex).

hint: String

Human-readable diagnostic from EXIT_CODE_HINTS.

SpawnFailed

Subprocess could not be spawned at all (binary missing, no exec permission, or the OS refused to fork). Distinct from NonZeroExit so call sites can branch on “never started” vs “started and crashed”.

Fields

binary: String

Path of the binary that was supposed to be spawned.

source: String

Underlying io::Error message (e.g. “No such file or directory”).

Timeout

Subprocess exceeded the per-call timeout (default 300s, override via SQLITE_GRAPHRAG_EMBED_TIMEOUT_SECS).

Fields

secs: u64

Configured timeout in seconds.

binary: String

Path of the binary that was running when the timeout fired.

NoBackendsAvailable

All backends in the fallback chain failed AND no fallback was available. The call site should honour --skip-embedding-on-failure to write a pending_embeddings row instead of propagating this.

Implementations

impl LlmBackendError

pub fn hint(&self) -> String

Returns the human-readable diagnostic for this error.

pub fn truncate_tail(raw: &[u8], max_bytes: usize) -> String

Truncates the tail of a UTF-8 string to max_bytes, breaking on a char boundary so the result is always valid UTF-8.

Trait Implementations

impl Clone for LlmBackendError

fn clone(&self) -> LlmBackendError

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for LlmBackendError

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for LlmBackendError

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Eq for LlmBackendError

impl Error for LlmBackendError

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.

impl PartialEq for LlmBackendError

fn eq(&self, other: &LlmBackendError) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl StructuralPartialEq for LlmBackendError