> For the complete documentation index, see [llms.txt](https://docs.talus.network/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.talus.network/talus-docs-v2.1.0/reference/sdk/errors.md).

# Error Types

**Audience:** Nexus SDK integrators (Rust).

**Area:** Error types.

**Generated from:** Nexus SDK public error API at release `v2.1.0` commit `45d397aafcfbeeeaf5032d5fb9fa5d99b3f36205`; the generated inventory is preserved and 2.1.0 variants are source-verified.

Fallible SDK operations return the source-defined error types below. Branch on their generated variants rather than matching display text. Historical Protocol-resolution errors belong only to the pinned [compatibility page](/talus-docs-v2.1.0/reference/sdk/protocol.md).

### 2.1.0 read and transaction errors

`NexusError::ObjectNotFound` is a definitive absence at the requested RPC read boundary. Keep it distinct from an RPC or transport failure, which means the endpoint could not establish whether the object exists. `NexusError::InvalidTransactionOutput` means a typed object result or transaction output could not be trusted for state inference; it is distinct from an object that is missing because a transaction has not reached the required finality boundary.

#### Sui transaction-expiration compatibility

The 2.1.0 SDK decodes both Sui protocol-137 transaction-expiration wire forms: `ValidDuring` and `Validity`. Both forms carry optional minimum and maximum epoch or timestamp bounds, a chain digest, and a nonce; `Validity` additionally carries the optional `AllowedProposers` value. This is SDK decoding compatibility for transaction data and does not imply a deployment or network upgrade.

### Source-derived public API inventory

#### `SDK_BUILD_IDENTITY`

```rust
pub const SDK_BUILD_IDENTITY: &str = env!("CARGO_PKG_VERSION");
```

#### `ClientUpgradeRequired`

```rust
pub struct ClientUpgradeRequired {
    /// Stable identity of the object that cannot be interpreted.
    pub object_id: sui::types::Address,
    /// Exact package witness observed on the object.
    pub witness_type: Box<sui::types::StructTag>,
    /// Exact inner layout when its metadata was available.
    pub inner_type: Option<Box<sui::types::StructTag>>,
    /// SDK build that performed the compatibility check.
    pub sdk_build: &'static str,
}
```

#### `ClientUpgradeRequired::new`

```rust
pub fn new(
        object_id: sui::types::Address,
        witness_type: sui::types::StructTag,
        inner_type: Option<sui::types::StructTag>,
    ) -> Self {
```

#### `TransactionErrorState`

```rust
pub enum TransactionErrorState {
    /// The network rejected the transaction before execution.
    SubmissionRejected,
    /// The client cannot prove whether the transaction reached the network.
    SubmissionUnknown,
    /// The transaction executed, but checkpoint confirmation is unknown.
    ConfirmationUnknown,
    /// The transaction was confirmed with failed effects.
    ExecutionFailed,
}
```

#### `TransactionError`

```rust
pub enum TransactionError {
    /// The transaction was rejected before execution.
    #[error("transaction {digest} was rejected before execution: {source}")]
    SubmissionRejected {
        digest: crate::sui::types::Digest,
        #[source]
        source: tonic::Status,
    },
    /// The transaction submission result is unknown.
    #[error("transaction {digest} submission state is unknown: {source}")]
    SubmissionUnknown {
        digest: crate::sui::types::Digest,
        #[source]
        source: tonic::Status,
    },
    /// The transaction executed, but did not reach a checkpoint in time.
    #[error(
        "transaction {digest} was executed but checkpoint confirmation is unknown after {timeout:?}"
    )]
    ConfirmationTimedOut {
        digest: crate::sui::types::Digest,
        timeout: Duration,
        response: Box<crate::sui::grpc::ExecuteTransactionResponse>,
    },
    /// The transaction executed, but checkpoint observation failed.
    #[error("transaction {digest} was executed but checkpoint confirmation failed: {source}")]
    ConfirmationFailed {
        digest: crate::sui::types::Digest,
        response: Box<crate::sui::grpc::ExecuteTransactionResponse>,
        #[source]
        source: tonic::Status,
    },
    /// The confirmation response omitted required transaction data.
    #[error("transaction {digest} confirmation response is invalid: {message}")]
    ConfirmationResponseInvalid {
        digest: crate::sui::types::Digest,
        response: Box<crate::sui::grpc::ExecuteTransactionResponse>,
        message: &'static str,
    },
    /// The transaction was confirmed with failed effects.
    #[error(
        "transaction {digest} failed at checkpoint {checkpoint} in command {command:?}: {error:?}"
    )]
    ExecutionFailed {
        digest: crate::sui::types::Digest,
        checkpoint: u64,
        error: crate::sui::types::ExecutionError,
        command: Option<u64>,
    },
}
```

#### `TransactionError::submission_rejected`

```rust
pub fn submission_rejected(digest: crate::sui::types::Digest, source: tonic::Status) -> Self {
```

#### `TransactionError::submission_unknown`

```rust
pub fn submission_unknown(digest: crate::sui::types::Digest, source: tonic::Status) -> Self {
```

#### `TransactionError::confirmation_timed_out`

```rust
pub fn confirmation_timed_out(
        digest: crate::sui::types::Digest,
        timeout: Duration,
        response: crate::sui::grpc::ExecuteTransactionResponse,
    ) -> Self {
```

#### `confirmation_failed`

```rust
pub fn confirmation_failed(
        digest: crate::sui::types::Digest,
        response: crate::sui::grpc::ExecuteTransactionResponse,
        source: tonic::Status,
    ) -> Self {
```

#### `confirmation_response_invalid`

```rust
pub fn confirmation_response_invalid(
        digest: crate::sui::types::Digest,
        response: crate::sui::grpc::ExecuteTransactionResponse,
        message: &'static str,
    ) -> Self {
```

#### `execution_failed`

```rust
pub fn execution_failed(
        digest: crate::sui::types::Digest,
        checkpoint: u64,
        error: crate::sui::types::ExecutionError,
        command: Option<u64>,
    ) -> Self {
```

#### `TransactionError::digest`

```rust
pub fn digest(&self) -> &crate::sui::types::Digest {
```

#### `TransactionError::state`

```rust
pub fn state(&self) -> TransactionErrorState {
```

#### `TransactionError::response`

```rust
pub fn response(&self) -> Option<&crate::sui::grpc::ExecuteTransactionResponse> {
```

#### `TransactionError::submission_rejection`

```rust
pub fn submission_rejection(&self) -> Option<&tonic::Status> {
```

#### `NexusError`

```rust
pub enum NexusError {
    #[error(transparent)]
    Transaction(Box<TransactionError>),
    #[error("a private key is required for this operation")]
    MissingPrivateKey,
    #[error("Sui wallet error: {0}")]
    Wallet(anyhow::Error),
    #[error("Client configuration error: {0}")]
    Configuration(String),
    #[error("a gas source is already configured")]
    GasSourceAlreadyConfigured,
    #[error("Transaction building error: {0}")]
    TransactionBuilding(anyhow::Error),
    #[error("RPC error: {0}")]
    Rpc(anyhow::Error),
    #[error("Parsing error: {0}")]
    Parsing(anyhow::Error),
    #[error("Timeout error: {0}")]
    Timeout(anyhow::Error),
    #[error("Channel error: {0}")]
    Channel(anyhow::Error),
    #[error("Storage error: {0}")]
    Storage(anyhow::Error),
    /// The connected Sui chain does not match [`crate::types::NexusObjects`].
    #[error("Connected chain '{actual}' does not match configured chain '{expected}'")]
    ChainMismatch { expected: String, actual: String },
    /// A live object violates the required anchor field structure.
    #[error("Object state for '{object}' is invalid: {reason}")]
    InvalidObjectState {
        object: sui::types::Address,
        reason: String,
    },
    /// A transaction response contains inconsistent output identity or state.
    #[error("Transaction '{transaction}' outputs are invalid: {reason}")]
    InvalidTransactionOutput {
        transaction: sui::types::Digest,
        reason: String,
    },
    /// A package is structurally valid but incompatible with an operation graph.
    #[error("Package '{package}' is incompatible: {reason}")]
    IncompatiblePackage {
        package: sui::types::Address,
        reason: String,
    },
    /// The node answered definitively that the object does not exist.
    #[error("Object '{object}' does not exist")]
    ObjectNotFound { object: sui::types::Address },
    /// The SDK does not contain an adapter for the observed object state.
    #[error(transparent)]
    ClientUpgradeRequired(#[from] ClientUpgradeRequired),
}
```

#### `NexusError::from_rpc`

```rust
pub fn from_rpc(error: anyhow::Error) -> Self {
```

#### `ErrorSource`

```rust
pub type ErrorSource = Box<dyn Error + Send + Sync + 'static>;
```

#### `ScheduleError`

```rust
pub enum ScheduleError {
    /// A Task cannot reserve zero MIST for an occurrence.
    #[error("occurrence budget must be greater than zero")]
    ZeroOccurrenceBudget,

    /// A Task entry group cannot be empty.
    #[error("entry group must not be empty")]
    EmptyEntryGroup,

    /// An absolute deadline precedes the known absolute start.
    #[error("occurrence deadline {deadline_ms}ms precedes its start {start_time_ms}ms")]
    DeadlineBeforeStart {
        /// Known absolute start timestamp.
        start_time_ms: u64,
        /// Invalid absolute deadline timestamp.
        deadline_ms: u64,
    },

    /// The priority fee is outside the protocol range.
    #[error("priority fee percentage must be in {minimum}..={maximum}, got {percentage}")]
    PriorityFeeOutOfRange {
        /// Invalid percentage.
        percentage: u64,
        /// Inclusive protocol minimum.
        minimum: u64,
        /// Inclusive protocol maximum.
        maximum: u64,
    },

    /// A recurrence interval must advance time.
    #[error("recurrence interval must be greater than zero")]
    ZeroRecurrenceInterval,

    /// A finite recurrence must contain at least one occurrence.
    #[error("finite recurrence occurrence count must be greater than zero")]
    ZeroRecurrenceCount,

    /// The atomic create and schedule shortcut requires work.
    #[error("schedule must contain at least one occurrence or a recurrence")]
    EmptySchedule,

    /// Resolving a relative timestamp exceeded the `u64` timestamp range.
    #[error("resolving {field} from {base_ms}ms with offset {offset_ms}ms overflowed")]
    TimeOverflow {
        /// Name of the timestamp being resolved.
        field: &'static str,
        /// Timestamp to which the offset was applied.
        base_ms: u64,
        /// Relative offset that overflowed.
        offset_ms: u64,
    },

    /// A Task operation and funding controller cannot be combined.
    #[error("{message}")]
    IncompatibleFunding {
        /// Explanation of the invalid combination.
        message: &'static str,
    },
}
```

#### `SchedulerError`

```rust
pub enum SchedulerError {
    /// A Task or Schedule authoring value is invalid.
    #[error(transparent)]
    Schedule(#[from] ScheduleError),

    /// The configured Nexus client could not complete the operation.
    #[cfg(feature = "nexus")]
    #[error(transparent)]
    Client(Box<NexusError>),

    /// The requested Task object does not exist.
    #[error("Task '{task_id}' was not found")]
    TaskNotFound {
        /// Missing Task identifier.
        task_id: sui::types::Address,
    },

    /// The requested occurrence record does not exist.
    #[error("occurrence {occurrence_id} was not found on Task '{task_id}'")]
    OccurrenceNotFound {
        /// Owning Task identifier.
        task_id: sui::types::Address,
        /// Missing occurrence identifier.
        occurrence_id: u64,
    },

    /// The requested operation requires a dispatched occurrence.
    #[error("occurrence {occurrence_id} on Task '{task_id}' has not been dispatched")]
    OccurrenceNotDispatched {
        /// Owning Task identifier.
        task_id: sui::types::Address,
        /// Occurrence identifier.
        occurrence_id: u64,
    },

    /// Settlement was requested from a lifecycle state other than `Finished`.
    #[error(
        "occurrence {occurrence_id} on Task '{task_id}' is not ready for settlement; expected \
         finished, observed {observed:?}"
    )]
    OccurrenceNotReadyForSettlement {
        /// Owning Task identifier.
        task_id: sui::types::Address,
        /// Occurrence identifier.
        occurrence_id: u64,
        /// Lifecycle state observed immediately before transaction construction.
        observed: OccurrenceStatus,
    },

    /// A selected DAG does not contain the requested Task entry group.
    #[error(
        "DAG '{dag_id}' does not contain Task entry group '{entry_group}'; available groups: \
         {available:?}"
    )]
    TaskEntryGroupNotFound {
        /// Selected DAG identifier.
        dag_id: sui::types::Address,
        /// Requested entry group.
        entry_group: String,
        /// Entry groups published by the DAG.
        available: Vec<String>,
    },

    /// Task inputs do not exactly match the selected DAG entry group.
    #[error(
        "Task inputs do not match entry group '{entry_group}' on DAG '{dag_id}'; expected shape \
         {expected}, received shape {received}"
    )]
    TaskInputsMismatch {
        /// Selected DAG identifier.
        dag_id: sui::types::Address,
        /// Selected entry group.
        entry_group: String,
        /// Required input JSON shape with placeholder values.
        expected: String,
        /// Supplied input JSON shape without user values.
        received: String,
    },

    /// One provided Task input does not conform to the immutable Tool schema stored on its DAG vertex.
    #[error(
        "Task input '{vertex}.{port}' on DAG '{dag_id}' does not conform to MetaSchema; expected \
         {expected}, received {received}"
    )]
    TaskInputSchemaMismatch {
        /// Effective DAG identifier.
        dag_id: sui::types::Address,
        /// Entry vertex name.
        vertex: String,
        /// Entry input port name.
        port: String,
        /// Required cardinality and value kind.
        expected: Box<str>,
        /// Received cardinality and value kind.
        received: Box<str>,
    },

    /// A pinned Agent skill forbids a caller-selected DAG, even when it repeats the pinned ID.
    #[error(
        "Agent '{agent_id}' skill {skill_id} is pinned to DAG '{pinned_dag}' and rejects caller-selected DAG '{selected_dag}'"
    )]
    PinnedSkillDagSelectionConflict {
        /// Selected Agent.
        agent_id: sui::types::Address,
        /// Selected Agent-local skill.
        skill_id: u64,
        /// Authoritative registered DAG.
        pinned_dag: sui::types::Address,
        /// Rejected caller-selected DAG.
        selected_dag: sui::types::Address,
    },

    /// A runtime-selected Agent skill requires the Task author to choose a DAG.
    #[error("Agent '{agent_id}' skill {skill_id} requires a caller-selected DAG")]
    RuntimeSelectedSkillDagRequired {
        /// Selected Agent.
        agent_id: sui::types::Address,
        /// Selected Agent-local skill.
        skill_id: u64,
    },

    /// The configured signer cannot satisfy the Task controller.
    #[error("authority for Task '{task_id}' is unavailable: {message}")]
    AuthorityUnavailable {
        /// Task whose controller cannot be resolved.
        task_id: sui::types::Address,
        /// Human readable authority mismatch.
        message: String,
    },

    /// An onchain object did not have the required type or shape.
    #[error("object '{object_id}' is invalid: {message}")]
    InvalidObject {
        /// Invalid object identifier.
        object_id: sui::types::Address,
        /// Human readable schema mismatch.
        message: String,
    },

    /// Binary Canonical Serialization failed at the Move boundary.
    #[error("scheduler BCS conversion failed")]
    Bcs(#[source] bcs::Error),

    /// RPC or network transport failed.
    #[error("scheduler transport failed: {source}")]
    Transport {
        /// Original transport failure.
        #[source]
        source: ErrorSource,
    },

    /// Programmable transaction construction failed.
    #[error("scheduler transaction construction failed: {source}")]
    Transaction {
        /// Original construction failure.
        #[source]
        source: ErrorSource,
    },

    /// A submitted transaction was not confirmed as expected.
    #[error("scheduler transaction confirmation failed: {message}")]
    Confirmation {
        /// Confirmation failure details.
        message: String,
    },

    /// Confirmed chain data violates the scheduler's structural invariants.
    #[error("inconsistent scheduler chain state: {message}")]
    InconsistentChainState {
        /// Invariant violation details.
        message: String,
    },

    /// A scheduler query option is invalid.
    #[error("invalid scheduler request: {message}")]
    InvalidRequest {
        /// Invalid request details.
        message: String,
    },

    /// Watching an occurrence reached its timeout.
    #[error("timed out while waiting for occurrence lifecycle completion")]
    WatchTimedOut {
        /// Last object backed snapshot observed before timeout.
        last_snapshot: Box<OccurrenceSnapshot>,
    },
}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.talus.network/talus-docs-v2.1.0/reference/sdk/errors.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `build a script that syncs our docs to a CMS` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.