influxdata/influxdb · critical · Error

failed to initialize catalog

Error message

failed to initialize catalog: {0}

What it means

Display message of the `Error::InitializeCatalog` variant, wrapping a `CatalogError` (#[source]) that occurred while loading or creating the catalog during serve startup. The catalog holds databases, tables, tokens, and schema metadata, so this aborts startup.

Solutions

1. Inspect the wrapped CatalogError source for the exact cause
2. Verify the object-store/DB holding the catalog is reachable and credentials are valid
3. Check for catalog format/version incompatibility after upgrading and migrate or restore from backup
4. Restore the catalog from a known-good backup if the stored snapshot is corrupt

Example fix

// before
# corrupt/legacy catalog in storage -> init fails
// after
# restore catalog backup compatible with this binary version, then:
influxdb3 serve --node-id=node1 ...

match serve_result {
    Err(Error::InitializeCatalog(src)) => eprintln!("catalog init failed: {src}"),
    ...
}

When it happens

Trigger: During `influxdb3 serve`, the catalog initialization step (loading existing catalog from storage or creating a fresh one) returns a `CatalogError`.

Common situations: Unreadable/corrupt catalog snapshot in the object store, version mismatch between catalog format and the binary, or permission problems on local catalog files.

Related errors

• catalog update error
• column id in series key should be valid
• Error converting max_columns_per_table
• Error converting max_tables
• Error converting object_store_id

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

Appendix: source

Thrown at influxdb3/src/commands/serve.rs:144

    #[error("Failed to bind address")]
    BindAddress(#[source] std::io::Error),

    #[error("Server error: {0}")]
    Server(#[source] influxdb3_server::Error),

    #[error("Token error: {0}")]
    TokenError(CatalogError),

    #[error("Write buffer error: {0}")]
    WriteBuffer(#[from] influxdb3_write::write_buffer::Error),

    #[error("invalid token: {0}")]
    InvalidToken(#[from] hex::FromHexError),

    #[error("failed to initialize write buffer: {0:?}")]
    WriteBufferInit(#[source] anyhow::Error),

    #[error("failed to initialize catalog: {0}")]
    InitializeCatalog(#[source] CatalogError),

    #[error("failed to initialize last cache: {0}")]
    InitializeLastCache(#[source] last_cache::Error),

    #[error("failed to initialize distinct cache: {0:#}")]
    InitializeDistinctCache(#[source] influxdb3_cache::distinct_cache::ProviderError),

    #[error("lost backend")]
    LostBackend,

    #[error("lost HTTP/gRPC service")]
    LostHttpGrpc,

    #[error("lost admin token recovery service")]
    LostAdminTokenRecovery,

    #[error("tls requires both a cert and a key file to be passed in to work")]

View on GitHub (pinned to 06200ef96b)