influxdata/influxdb · critical · CatalogError

unexpected internal error

Error message

unexpected internal error

What it means

A generic catch-all for unexpected internal errors in the influxdb3_catalog crate. `CatalogError::unexpected(message)` wraps the message into `Other` via `anyhow!`, and thisclippy-style `Other(anyhow::Error)` variant renders as "unexpected internal error" when no message is attached or the anyhow context is stripped. It signals a bug or an unanticipated condition rather than an operator-actionable failure.

Solutions

1. Read the full error chain/logs for the anyhow context message to identify the actual internal failure
2. Check for known issues in the influxdb3 version in use and upgrade to the latest patch release
3. Capture catalog files and report with reproduction steps if it persists
4. Validate catalog data integrity (backups/restore) if corruption is suspected

match result {
    Err(CatalogError::Other(e)) => {
        log::error("unexpected catalog internal error: {e:#}");
        // alert/abort — this is a bug or corruption, not user error
    }
    r => r?,
}

When it happens

Trigger: Any code path calling `CatalogError::unexpected(...)` or constructing the `Other` variant — internal assertions, unhandled repository states, or bugs surfacing through the public error enum.

Common situations: Hitting an unreachable-but-reached code branch after a version change; catalog corruption causing impossible states; bugs in the write/apply path reported by users.

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

• By the point that we're doing partitioning, we should've…
• catalog internal error
• error
• Existing transaction for table should not exist
• mapped to out-of-bounds shard

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

Appendix: source

Thrown at influxdb3_catalog/src/error.rs:412

    #[error(
        "node '{node_id}' cannot clear its connection address (conn info e.g. 8181) while it is a member of query group '{query_group_name}' (id {query_group_id})"
    )]
    NodeConnInfoRequiredInQueryGroup {
        node_id: Arc<str>,
        query_group_name: Arc<str>,
        query_group_id: QueryGroupId,
    },
}

impl CatalogError {
    pub fn invalid_configuration(message: impl AsRef<str>) -> Self {
        Self::InvalidConfiguration {
            message: Box::from(message.as_ref()),
        }
    }

    pub fn unexpected(message: impl Into<String>) -> Self {
        Self::Other(anyhow!(message.into()))
    }

    pub(crate) fn too_many_columns(
        table_name: impl Into<Arc<str>>,
        attempted: usize,
        limit: usize,
    ) -> Self {
        Self::TooManyColumns {
            table_name: TruncatedTableName::new(table_name),
            attempted,
            limit,
        }
    }

    pub(crate) fn too_many_tag_columns(
        table_name: impl Into<Arc<str>>,
        attempted: usize,
        limit: usize,

View on GitHub (pinned to 06200ef96b)