{"record":{"id":"00aeb7ce19bbe8b4","repo":"influxdata/influxdb","slug":"catalog-internal-error-details","errorCode":null,"errorMessage":"catalog internal error: {details}","messagePattern":"catalog internal error: (.+?)","errorType":"error_code","errorClass":"CatalogError","httpStatus":500,"severity":"error","filePath":"influxdb3_catalog/src/error.rs","lineNumber":64,"sourceCode":"\n    #[error(\"catalog format error: {0}\")]\n    Format(#[from] FormatError),\n\n    #[error(\"attempted to create a resource that already exists\")]\n    AlreadyExists,\n\n    #[error(\"the requested resource was not found: {0}\")]\n    NotFound(String),\n\n    #[error(\"attempted to modify resource that was already deleted: {0}\")]\n    AlreadyDeleted(String),\n\n    /// Request is idempotent: no catalog state would change.\n    #[error(\"no catalog changes to apply: {details}\")]\n    NoCatalogChange { details: String },\n\n    /// Request is invalid.\n    #[error(\"catalog internal error: {details}\")]\n    Internal { details: String },\n\n    #[error(\n        \"persisted catalog checkpoint sequence {checkpoint_sequence} is ahead of live catalog sequence {live_sequence}\"\n    )]\n    BackupCheckpointAhead {\n        checkpoint_sequence: u64,\n        live_sequence: u64,\n    },\n\n    #[error(\"invalid configuration provided: {message}\")]\n    InvalidConfiguration { message: Box<str> },\n\n    #[error(\"only tag and string columns are supported in the distinct cache\")]\n    InvalidDistinctCacheColumnType,\n\n    #[error(\"only uint64, int64, bool, tag, and string columns are supported in the last cache\")]\n    InvalidLastCacheKeyColumnType,","sourceCodeStart":46,"sourceCodeEnd":82,"githubUrl":"https://github.com/influxdata/influxdb/blob/06200ef96ba82c5f6727e5038a83af8e722c6875/influxdb3_catalog/src/error.rs#L46-L82","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read details to identify the invalid input and correct the caller","Update influxdb3 crates to consistent versions","File a bug with the details text and reproduction if inputs look valid","Catch CatalogError::Internal and log at error level; do not retry blindly"],"exampleFix":"// before\n// altering a table snapshot fetched from another catalog instance\nlet table = other_catalog.db(\"d\")?.table(\"t\")?;\nmy_catalog.alter_table(table)?.execute().await?;\n// after\nlet table = my_catalog.db(\"d\")?.table(\"t\")?;\nmy_catalog.alter_table(table)?.execute().await?;","handlingStrategy":"try-catch","validationCode":"// Validate inputs against catalog public APIs; avoid constructing TableDefinition manually\nlet table = my_catalog.db(\"d\")?.table(\"t\")?; // fetch from the same catalog instance","typeGuard":"fn is_internal(err: &CatalogError) -> Option<&str> {\n    match err { CatalogError::Internal { details } => Some(details), _ => None }\n}","tryCatchPattern":"match catalog_op().await {\n    Err(CatalogError::Internal { details }) => {\n        tracing::error!(\"catalog internal error: {details}\");\n        // do not retry; report/bug with details\n    }\n    other => other?,\n}","preventionTips":["Only use public catalog APIs; keep objects from one catalog instance out of another","Keep all influxdb3 crates at the same version","Capture the details string in bug reports","Add assertions around hand-built definitions"],"tags":["internal","invariant","catalog"],"backgroundTag":"internal-invariant-violation","analyzedSha":"06200ef96ba82c5f6727e5038a83af8e722c6875","analyzedAt":"2026-09-19T12:55:30.003Z","contentChangedAt":"2026-09-19T12:55:30.003Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}