Implementation:Lance format Lance NamespaceError

Knowledge Sources	Lance
Domains	Namespace, Error_Handling
Last Updated	2026-02-08 19:33 GMT

Overview

Description

The NamespaceError module defines fine-grained error types for Lance Namespace operations. It provides two primary types:

• ErrorCode -- A #[repr(u32)] enum with 21 numeric error codes (0 through 20) that are consistent across all Lance Namespace implementations (Python, Java, Rust, REST). This enables programmatic error handling across language boundaries.
• NamespaceError -- A snafu-derived error enum with one variant per error code. Each variant carries a message: String field for human-readable context.

The module also provides bidirectional conversion between NamespaceError and lance_core::Error, preserving the original error for later downcasting. The from_code constructor allows creating errors from numeric codes received from REST APIs or other language bindings.

Usage

Namespace implementations return NamespaceError for operation-specific failures. These are converted to lance_core::Error::Namespace at the integration boundary. Consumers can downcast the boxed source to recover the original NamespaceError and inspect its code() for programmatic handling.

Code Reference

Source Location

rust/lance-namespace/src/error.rs

Signature

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[repr(u32)]
pub enum ErrorCode {
    Unsupported = 0,
    NamespaceNotFound = 1,
    NamespaceAlreadyExists = 2,
    NamespaceNotEmpty = 3,
    TableNotFound = 4,
    TableAlreadyExists = 5,
    // ... through TableSchemaValidationError = 20
}

#[derive(Debug, Snafu)]
pub enum NamespaceError {
    Unsupported { message: String },
    NamespaceNotFound { message: String },
    // ... one variant per ErrorCode
}

impl NamespaceError {
    pub fn code(&self) -> ErrorCode;
    pub fn from_code(code: u32, message: impl Into<String>) -> Self;
}

Import

use lance_namespace::{NamespaceError, ErrorCode};

I/O Contract

Inputs

Parameter	Type	Description
code	u32	Numeric error code for from_code constructor; unrecognized codes map to Internal
message	impl Into<String>	Human-readable error message

Outputs

Type	Description
ErrorCode	The numeric error code associated with this error (via code())
lance_core::Error	Converted error preserving the original NamespaceError in its source field (via From)

Usage Examples

use lance_namespace::{NamespaceError, ErrorCode};

// Create a typed error
let err = NamespaceError::TableNotFound {
    message: "Table 'users' not found".into(),
};
assert_eq!(err.code(), ErrorCode::TableNotFound);
assert_eq!(err.code().as_u32(), 4);

// Reconstruct from a numeric code (e.g., from REST response)
let err = NamespaceError::from_code(4, "table not found");
assert_eq!(err.code(), ErrorCode::TableNotFound);

// Convert to lance_core::Error for propagation
let lance_err: lance_core::Error = err.into();

Related Pages

• Lance_format_Lance_LanceNamespaceTrait -- The trait whose methods return these errors
• Lance_format_Lance_NamespaceSchema -- Schema conversion utilities in the same crate
• Lance_format_Lance_RestApi -- REST API specification that uses the same error codes