influxdata/influxdb · error · CatalogError

catalog internal error

Error message

catalog internal error: {details}

What it means

CatalogError::Internal { details } signals an invalid request or an unexpected internal condition in the catalog library that should not normally occur. It is the catch-all for invariant violations within catalog processing, with details describing the specific problem. Usually points to a bug or misuse of internal APIs rather than user configuration.

Solutions

1. Read details to identify the invalid input and correct the caller
2. Update influxdb3 crates to consistent versions
3. File a bug with the details text and reproduction if inputs look valid
4. Catch CatalogError::Internal and log at error level; do not retry blindly

Example fix

// before
// altering a table snapshot fetched from another catalog instance
let table = other_catalog.db("d")?.table("t")?;
my_catalog.alter_table(table)?.execute().await?;
// after
let table = my_catalog.db("d")?.table("t")?;
my_catalog.alter_table(table)?.execute().await?;

// Validate inputs against catalog public APIs; avoid constructing TableDefinition manually
let table = my_catalog.db("d")?.table("t")?; // fetch from the same catalog instance

fn is_internal(err: &CatalogError) -> Option<&str> {
    match err { CatalogError::Internal { details } => Some(details), _ => None }
}

match catalog_op().await {
    Err(CatalogError::Internal { details }) => {
        tracing::error!("catalog internal error: {details}");
        // do not retry; report/bug with details
    }
    other => other?,
}

When it happens

Trigger: Calling catalog internals with inconsistent inputs (e.g., altering columns on a table view that is out of sync); requests rejected by internal validation that has no dedicated variant; unexpected state discovered while processing a catalog batch.

Common situations: Embedded use of influxdb3_catalog with hand-constructed arguments; version-skew between crates sharing a catalog; genuine library bugs — worth reporting with the details string.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• Existing transaction for table should not exist
• ordered catalog batch should contain changes
• unexpected internal error
• {0}
• Adding a new database would exceed limit of

AI-assisted analysis of influxdata/influxdb@06200ef96b (2026-09-19). Data as JSON: /api/errors/00aeb7ce19bbe8b4. Report an issue: GitHub.

Appendix: source

Thrown at influxdb3_catalog/src/error.rs:64

    #[error("catalog format error: {0}")]
    Format(#[from] FormatError),

    #[error("attempted to create a resource that already exists")]
    AlreadyExists,

    #[error("the requested resource was not found: {0}")]
    NotFound(String),

    #[error("attempted to modify resource that was already deleted: {0}")]
    AlreadyDeleted(String),

    /// Request is idempotent: no catalog state would change.
    #[error("no catalog changes to apply: {details}")]
    NoCatalogChange { details: String },

    /// Request is invalid.
    #[error("catalog internal error: {details}")]
    Internal { details: String },

    #[error(
        "persisted catalog checkpoint sequence {checkpoint_sequence} is ahead of live catalog sequence {live_sequence}"
    )]
    BackupCheckpointAhead {
        checkpoint_sequence: u64,
        live_sequence: u64,
    },

    #[error("invalid configuration provided: {message}")]
    InvalidConfiguration { message: Box<str> },

    #[error("only tag and string columns are supported in the distinct cache")]
    InvalidDistinctCacheColumnType,

    #[error("only uint64, int64, bool, tag, and string columns are supported in the last cache")]
    InvalidLastCacheKeyColumnType,

View on GitHub (pinned to 06200ef96b)