Enum AppError 

pub enum AppError {
    Validation(String),
    Duplicate(String),
    Conflict(String),
    NotFound(String),
    NamespaceError(String),
    LimitExceeded(String),
    Database(Error),
    Embedding(String),
    VecExtension(String),
    DbBusy(String),
    BatchPartialFailure {
        total: usize,
        failed: usize,
    },
    Io(Error),
    Internal(Error),
    Json(Error),
    LockBusy(String),
    AllSlotsFull {
        max: usize,
        waited_secs: u64,
    },
    LowMemory {
        available_mb: u64,
        required_mb: u64,
    },
}

Unified error type for all CLI and library operations.

Each variant corresponds to a distinct failure category. The AppError::exit_code method converts a variant into a stable numeric code so that shell callers and LLM agents can route on it.

Variants

Validation(String)

Input failed schema, length or format validation. Maps to exit code 1.

Duplicate(String)

A memory or entity with the same (namespace, name) already exists. Maps to exit code 2.

Conflict(String)

Optimistic update lost the race because updated_at changed. Maps to exit code 3.

NotFound(String)

The requested record does not exist or was soft-deleted. Maps to exit code 4.

NamespaceError(String)

Namespace could not be resolved from flag, environment or markers. Maps to exit code 5.

LimitExceeded(String)

Payload exceeded one of the configured body, name or batch limits. Maps to exit code 6.

Database(Error)

Low-level SQLite error propagated from rusqlite. Maps to exit code 10.

Embedding(String)

Embedding generation via fastembed failed or produced the wrong shape. Maps to exit code 11.

VecExtension(String)

The sqlite-vec extension could not load or register its virtual table. Maps to exit code 12.

DbBusy(String)

SQLite returned SQLITE_BUSY after exhausting retries. Maps to exit code 15 (antes de v2.0.0 era 13; movido para liberar 13 para BatchPartialFailure conforme PRD).

BatchPartialFailure

Batch operation failed partially — N of M items failed. Maps to exit code 13 (PRD 1822).

Reserved for use in import, reindex and batch stdin (BLOCK 3/4). Variant present since v2.0.0 even if call-sites do not yet exist — stable exit code mapping.

Fields

total: usize

failed: usize

Io(Error)

Filesystem I/O error while reading or writing the database or cache. Maps to exit code 14.

Internal(Error)

Unexpected internal error surfaced through anyhow. Maps to exit code 20.

Json(Error)

JSON serialization or deserialization failure. Maps to exit code 20.

LockBusy(String)

Another instance is already running and holds the advisory lock. Maps to exit code 75.

Use --allow-parallel to skip the lock or --wait-lock SECONDS to retry.

AllSlotsFull

All concurrency slots are occupied after the wait timeout. Maps to exit code 75.

Occurs when crate::constants::MAX_CONCURRENT_CLI_INSTANCES instances are already active and the wait limit crate::constants::CLI_LOCK_DEFAULT_WAIT_SECS is exhausted.

Fields

max: usize

waited_secs: u64

LowMemory

Available memory is below the minimum required to load the model. Maps to exit code 77.

Returned when sysinfo reports available memory below crate::constants::MIN_AVAILABLE_MEMORY_MB MiB before starting the ONNX model load.

Fields

available_mb: u64

required_mb: u64

Implementations

impl AppError

pub fn exit_code(&self) -> i32

Returns the deterministic process exit code for this error variant.

The codes follow the contract documented in the README: 1 for validation, 2 for duplicates, 3 for conflicts, 4 for missing records, 5 for namespace errors, 6 for limit violations, 10–14 for infrastructure failures, 13 for BatchPartialFailure (PRD 1822), 15 for DbBusy (migrated from 13 in v2.0.0), 20 for internal errors, 75 (EX_TEMPFAIL) when the advisory CLI lock is held or all concurrency slots are exhausted, and 77 when available memory is insufficient to load the embedding model.

Examples

use sqlite_graphrag::errors::AppError;

assert_eq!(AppError::Validation("invalid field".into()).exit_code(), 1);
assert_eq!(AppError::Duplicate("ns/mem".into()).exit_code(), 2);
assert_eq!(AppError::Conflict("ts changed".into()).exit_code(), 3);
assert_eq!(AppError::NotFound("id 42".into()).exit_code(), 4);
assert_eq!(AppError::NamespaceError("no marker".into()).exit_code(), 5);
assert_eq!(AppError::LimitExceeded("body too large".into()).exit_code(), 6);
assert_eq!(AppError::Embedding("wrong dim".into()).exit_code(), 11);
assert_eq!(AppError::DbBusy("retries exhausted".into()).exit_code(), 15);
assert_eq!(AppError::LockBusy("another instance".into()).exit_code(), 75);

pub fn localized_message(&self) -> String

Returns the localized error message in the active language (--lang / SQLITE_GRAPHRAG_LANG).

In English the text is identical to the Display generated by thiserror. In Portuguese the prefixes and messages are translated to PT-BR.

pub fn localized_message_for(&self, lang: Language) -> String

Returns the localized message for the explicitly provided language. Useful in tests that cannot depend on the global OnceLock.

Examples

use sqlite_graphrag::errors::AppError;
use sqlite_graphrag::i18n::Language;

let err = AppError::NotFound("mem-xyz".into());

let en = err.localized_message_for(Language::English);
assert!(en.contains("not found"));

let pt = err.localized_message_for(Language::Portuguese);
assert!(pt.contains("not found"));

Trait Implementations

impl Debug for AppError

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

Formats the value using the given formatter.

impl Display for AppError

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

Formats the value using the given formatter.

impl Error for AppError

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 From<Error> for AppError

fn from(source: Error) -> Self

Converts to this type from the input type.

impl From<Error> for AppError

fn from(source: Error) -> Self

Converts to this type from the input type.

impl From<Error> for AppError

fn from(source: Error) -> Self

Converts to this type from the input type.

impl From<Error> for AppError

fn from(source: Error) -> Self

Converts to this type from the input type.