Enum StorageError 

pub enum StorageError {
    MemoryNotFound {
        id: String,
        role: Option<LinkEnd>,
    },
    PendingActionNotFound {
        pending_id: String,
    },
    AmbiguousIdPrefix {
        prefix: String,
        candidates: Vec<String>,
    },
    InvalidArgument {
        reason: String,
    },
    PendingActionStateInvalid {
        pending_id: String,
        status: String,
    },
    LinkPermissionDenied {
        reason: String,
    },
    LinkReflectionCycle {
        source_id: String,
        target_id: String,
    },
    ApproverLaundering {
        pending_id: String,
        claimed: String,
        requester: String,
    },
    UniqueConflict {
        reason: String,
    },
    ArchiveRestoreCollision {
        id: String,
    },
    ArchiveSupersedeFailed {
        archived_id: String,
    },
    SqlcipherMissingPassphrase,
}

Typed substrate-layer error categories. Each variant maps to a canonical HTTP status via MemoryError::from(anyhow::Error) and preserves the original bail!() message verbatim via Display so downstream .to_string().starts_with(...) and .contains(...) consumers keep working through the typed layer.

Variants

MemoryNotFound

Memory id (or link source/target memory id) does not resolve to a row. role = None is the bare lookup (“memory not found: <id>”); role = Some(Source|Target) qualifies the message for link-creation paths.

Fields

id: String

role: Option<LinkEnd>

PendingActionNotFound

Pending-action lookup miss in the approvals path.

Fields

pending_id: String

AmbiguousIdPrefix

Truncated id prefix matches multiple memories. The full candidate list is surfaced so the caller can retry with a longer prefix.

Fields

prefix: String

candidates: Vec<String>

InvalidArgument

Caller-supplied argument failed substrate validation. Covers max_depth bounds, older_than_days sign, namespace shape, action_type, reflect-payload shape, and similar simple validations that map to HTTP 400.

Fields

reason: String

PendingActionStateInvalid

Pending action exists but cannot be executed in its current status (substrate refuses to execute non-approved actions).

Fields

pending_id: String

status: String

LinkPermissionDenied

Substrate-level link permission denied (governance Deny, or Ask→Deny because the storage layer has no Ask channel). Display starts with LINK_PERMISSION_DENIED_ERR_PREFIX.

Fields

reason: String

LinkReflectionCycle

Adding the proposed reflects_on edge would close a cycle in the reflection DAG. Display starts with LINK_CYCLE_ERR_PREFIX.

Fields

source_id: String

target_id: String

ApproverLaundering

Approver-on-behalf laundering refused (S5-H4): the claimed payload agent_id does not match the original requested_by.

Fields

pending_id: String

claimed: String

requester: String

UniqueConflict

Title / uniqueness conflict (existing memory or entity collision in the same namespace, or backend exhaustion of versioned-title suffixes within the cap).

Fields

reason: String

ArchiveRestoreCollision

Restore-from-archive would overwrite an active-table row. The caller must explicitly delete the active row first or restore to a different id.

Fields

id: String

ArchiveSupersedeFailed

Archive supersede transaction did not affect the expected row. Either the archive row vanished between read and write, or the DB is corrupt.

Fields

archived_id: String

SqlcipherMissingPassphrase

SQLCipher build started without AI_MEMORY_DB_PASSPHRASE. Fatal at boot; surfaces as an apply_sqlcipher_key refusal.

Implementations

impl StorageError

pub fn code(&self) -> &'static str

ARCH-9 (FX-C4-batch2, 2026-05-26) — canonical stable error slug for each variant.

Returns a &'static str that mirrors the crate::errors::MemoryError::code discipline. The slug is the load-bearing key for cross-surface (HTTP/MCP/CLI) parity tests and for structured-trace fields. Adding a variant requires extending this match — the #[deny(unreachable_patterns)] attribute on the outer match catches dead arms; the test arch_9_storage_error_slug_* in [crate::errors::error_codes::tests] pins the slug-set against a regression.

Trait Implementations

impl Clone for StorageError

fn clone(&self) -> StorageError

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for StorageError

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

Formats the value using the given formatter.

impl Display for StorageError

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

Formats the value using the given formatter.

impl Error for StorageError

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.