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).

Reservado para uso em import, reindex e batch stdin (BLOCO 3/4). Variante presente desde v2.0.0 mesmo que call-sites ainda não existam — mapeamento estável de exit code.

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

Todos os slots de concorrência estão ocupados após o tempo de espera. Maps to exit code 75.

Ocorre quando crate::constants::MAX_CONCURRENT_CLI_INSTANCES instâncias já estão ativas e o limite de espera crate::constants::CLI_LOCK_DEFAULT_WAIT_SECS foi esgotado.

Fields

max: usize

waited_secs: u64

LowMemory

Memória disponível abaixo do mínimo para carregar o modelo. Maps to exit code 77.

Retornado quando sysinfo reporta memória disponível inferior a crate::constants::MIN_AVAILABLE_MEMORY_MB MiB antes de iniciar o carregamento ONNX.

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("campo inválido".into()).exit_code(), 1);
assert_eq!(AppError::Duplicate("ns/mem".into()).exit_code(), 2);
assert_eq!(AppError::Conflict("ts mudou".into()).exit_code(), 3);
assert_eq!(AppError::NotFound("id 42".into()).exit_code(), 4);
assert_eq!(AppError::NamespaceError("sem marcador".into()).exit_code(), 5);
assert_eq!(AppError::LimitExceeded("corpo grande".into()).exit_code(), 6);
assert_eq!(AppError::Embedding("dim errada".into()).exit_code(), 11);
assert_eq!(AppError::DbBusy("retries esgotados".into()).exit_code(), 15);
assert_eq!(AppError::LockBusy("outra instância".into()).exit_code(), 75);

pub fn localized_message(&self) -> String

Retorna a mensagem de erro localizada no idioma ativo (--lang / SQLITE_GRAPHRAG_LANG).

Em inglês, o texto é idêntico ao Display gerado por thiserror. Em português, os prefixos e mensagens são traduzidos para PT-BR.

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

Retorna a mensagem localizada para o idioma explicitamente fornecido. Útil em testes que não podem depender do OnceLock global.

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::Portugues);
assert!(pt.contains("não encontrado"));

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.