Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Errors Reference (IC)

Note: This is the IC-specific error handling reference. For the complete error hierarchy, all error variants, and their causes, see the generic errors reference.


Overview

When using ic-dbms through the ic-dbms-client crate, error handling has an additional layer compared to direct wasm-dbms usage. The IC’s inter-canister call model introduces network-level errors alongside database-level errors, resulting in the double Result pattern.


IcDbmsError

IcDbmsError is the error type returned by every endpoint of an ic-dbms canister. It wraps the engine’s DbmsError and adds the access control errors, which the engine knows nothing about:

#![allow(unused)]
fn main() {
use ic_dbms_api::prelude::IcDbmsError;

pub enum IcDbmsError {
    /// The canister access control list refused the call.
    Acl(AclError),
    /// The database engine reported an error.
    Dbms(DbmsError),
    /// The SQL front-end rejected or failed to run a statement
    /// (only with the `sql` feature).
    Sql(SqlError),
}

pub enum AclError {
    AccessDenied {
        required: AclRequirement,
        table: Option<String>,
    },
    AdminGrantWithTable,
    AnonymousPrincipal,
    InvalidTable(String),
    LastAdmin,
}
}

DbmsError (Memory, Migration, Query, Sanitize, Table, Transaction, Validation) is documented in the generic errors reference. IcDbmsError implements From for DbmsError, AclError, SqlError and every engine error enum, so ? works in code that mixes them.


AclError

VariantMeaning
AccessDenied { required, table }The caller lacks required; table names the table for permission-specific operations.
AdminGrantWithTableAn Admin grant named a table; Admin always covers every table.
AnonymousPrincipalGrants cannot be given to the anonymous principal.
InvalidTable(name)The grant named an unknown or reserved table.
LastAdminThe operation would remove the last Admin grant.

required is AclRequirement::Permission(permission) for operations needing a specific permission. It is AclRequirement::AnyGrant when begin_transaction is called by a principal holding no grants.

#![allow(unused)]
fn main() {
use ic_dbms_api::prelude::{AclError, IcDbmsError};

match res {
    Ok(()) => {}
    Err(IcDbmsError::Acl(AclError::AccessDenied { required, table })) => {
        eprintln!("missing access: {required} on {table:?}");
    }
    Err(IcDbmsError::Acl(AclError::LastAdmin)) => {
        eprintln!("grant another admin first");
    }
    Err(other) => return Err(other),
}
}

SqlError

With the sql feature, the sql and sql_query endpoints return IcDbmsError::Sql(SqlError) when a statement cannot be parsed, planned or run. The variants are defined by wasm-dbms and documented in the wasm-dbms SQL reference. Two cases are specific to canisters:

  • SqlError::Unsupported with the message sql_query only runs SELECT statements; use sql for writes and transactions, returned by sql_query for any other statement.
  • SqlError::UnknownTable("ic_dbms_acl") for any statement that names the reserved access control table.

Engine errors raised while running a statement, such as a primary key conflict, arrive as SqlError::Runtime(DbmsError).

Double Result Pattern

Why Two Results?

Client operations return Result<Result<T, IcDbmsError>, CallError>:

Result<                          -- Outer: IC call result
    Result<T, IcDbmsError>,      -- Inner: Database operation result
    CallError                    -- Network/canister call error
>
  • Outer Result (CallError): The inter-canister call itself failed. This happens when:

    • The canister is unreachable or stopped
    • The canister ran out of cycles
    • The message was rejected (e.g., unauthorized caller)
    • Network timeout on agent calls
  • Inner Result (IcDbmsError): The call succeeded but the database operation failed. This happens when:

    • Primary key conflict
    • Foreign key constraint violation
    • Validation failure
    • Transaction not found
    • Any other database logic error

Using the ?? Operator

The simplest approach is to use ?? to unwrap both layers:

#![allow(unused)]
fn main() {
// Propagates both CallError and IcDbmsError
let users = client.select::<User>(User::table_name(), query, None).await??;
}

This requires your function to return an error type that both CallError and IcDbmsError can convert into (e.g., Box<dyn std::error::Error>, anyhow::Error, or a custom enum).

Explicit Error Handling

#![allow(unused)]
fn main() {
match client.insert::<User>(User::table_name(), user, None).await {
    Ok(Ok(())) => {
        // Success: call succeeded AND database operation succeeded
        println!("Insert successful");
    }
    Ok(Err(db_error)) => {
        // Call succeeded but database operation failed
        println!("Database error: {:?}", db_error);
    }
    Err(call_error) => {
        // Inter-canister call itself failed
        println!("Call failed: {:?}", call_error);
    }
}
}

Client Error Handling Examples

Basic Pattern

#![allow(unused)]
fn main() {
use ic_dbms_api::prelude::{DbmsError, IcDbmsError, QueryError};

let result = client.insert::<User>(User::table_name(), user, None).await;

match result {
    Ok(Ok(())) => println!("Insert successful"),
    Ok(Err(e)) => println!("Database error: {:?}", e),
    Err(e) => println!("Call failed: {:?}", e),
}
}

Detailed Matching

#![allow(unused)]
fn main() {
match client.insert::<User>(User::table_name(), user, None).await {
    Ok(Ok(())) => {
        println!("Insert successful");
    }
    Ok(Err(db_error)) => {
        match db_error {
            IcDbmsError::Dbms(DbmsError::Query(QueryError::PrimaryKeyConflict)) => {
                println!("User already exists");
            }
            IcDbmsError::Dbms(DbmsError::Query(QueryError::BrokenForeignKeyReference { .. })) => {
                println!("Referenced record doesn't exist");
            }
            IcDbmsError::Dbms(DbmsError::Validation(msg)) => {
                println!("Validation error: {}", msg);
            }
            _ => {
                println!("Database error: {:?}", db_error);
            }
        }
    }
    Err(call_error) => {
        println!("Failed to call canister: {:?}", call_error);
    }
}
}

Helper Function Pattern

#![allow(unused)]
fn main() {
fn handle_db_error(error: IcDbmsError) -> String {
    match error {
        IcDbmsError::Dbms(DbmsError::Query(QueryError::PrimaryKeyConflict)) => {
            "Record with this ID already exists".to_string()
        }
        IcDbmsError::Dbms(DbmsError::Query(QueryError::BrokenForeignKeyReference { .. })) => {
            "Referenced record not found".to_string()
        }
        IcDbmsError::Dbms(DbmsError::Query(QueryError::ForeignKeyConstraintViolation {
            ..
        })) => "Cannot delete: record has dependencies".to_string(),
        IcDbmsError::Dbms(DbmsError::Validation(msg)) => format!("Invalid data: {}", msg),
        _ => format!("Unexpected error: {:?}", error),
    }
}
}
#![allow(unused)]
fn main() {
// Usage
let result = client.insert::<User>(User::table_name(), user, None).await;
match result {
    Ok(Ok(())) => Ok(()),
    Ok(Err(e)) => Err(handle_db_error(e)),
    Err(e) => Err(format!("Call failed: {:?}", e)),
}
}

Retry Pattern for Transient Errors

Network-level errors (outer Result) may be transient. Database errors (inner Result) are deterministic and should not be retried.

#![allow(unused)]
fn main() {
use candid::CandidType;
use ic_dbms_api::prelude::{InsertRecord, TableSchema};
use ic_dbms_client::prelude::Client;

async fn insert_with_retry<T>(
    client: &impl Client,
    table: &str,
    record: T::Insert,
    max_retries: u32,
) -> Result<(), String>
where
    T: TableSchema,
    T::Insert: InsertRecord<Schema = T> + CandidType + Clone,
{
    for attempt in 0..max_retries {
        match client.insert::<T>(table, record.clone(), None).await {
            Ok(Ok(())) => return Ok(()),
            Ok(Err(e)) => {
                // Database errors are deterministic - don't retry
                return Err(format!("Database error: {:?}", e));
            }
            Err(call_err) => {
                // Call errors might be transient - retry
                if attempt < max_retries - 1 {
                    println!("Attempt {} failed, retrying...", attempt + 1);
                    continue;
                }
                return Err(format!(
                    "Call failed after {} attempts: {:?}",
                    max_retries, call_err
                ));
            }
        }
    }
    unreachable!()
}
}