influxdata/influxdb · critical

cannot create internal db

Error message

cannot create internal db

What it means

During catalog bootstrap the library attempts to create an internal database. If creation returns any error other than 'already exists', the code logs it and panics with 'cannot create internal db', because the process cannot operate without its internal db.

Solutions

1. Read the logged 'unexpected error when creating internal db' line — it carries the underlying cause (permissions, storage, etc.).
2. Fix storage permissions/availability: ensure the data directory is writable by the influxdb3 process and the disk is not full.
3. Verify object-store configuration (bucket, endpoint, credentials) if using remote storage.
4. If the catalog store is corrupted or half-migrated, restore from backup or re-bootstrap on a clean store.
5. Upgrade influxdb3 if the failure stems from a known migration bug in your version.

// before startup, verify storage is writable/available
if !storage.is_reachable() || !storage.can_write() {
    return Err("catalog storage unavailable; cannot create internal db");
}

fn storage_ready(cfg: &StorageConfig) -> bool {
    cfg.endpoint_resolves() && cfg.credentials_present() && cfg.path_writable()
}

// The library panics on unexpected creation errors; supervise the process.
loop {
    match run_influxdb3().await {
        Ok(()) => break,
        Err(e) | Err(_) if is_panic(&e) => {
            log::error!("catalog bootstrap failed: {e}; retrying after backoff");
            tokio::time::sleep(Duration::from_secs(5)).await;
        }
    }
}

When it happens

Trigger: The create-internal-db call returns an unexpected error — e.g. permission denied on the storage path, object store misconfiguration, disk full, schema version conflicts — anything other than the AlreadyExists variant.

Common situations: Data directory owned by the wrong user or read-only filesystem; S3/object store credentials or bucket misconfigured; corrupted or partially-migrated catalog store after a failed upgrade; disk-full on local storage.

Related errors

• at least one expr
• auto field family exists
• Azure blob storage support not enabled, recompile with the…
• By the point that we're doing partitioning, we should've…
• can only accept once

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

Appendix: source

Thrown at influxdb3_catalog/src/catalog/versions/v2.rs:1301

    let result = catalog
        .create_database_opts(
            INTERNAL_DB_NAME,
            CreateDatabaseOptions::default().retention_period(INTERNAL_DB_RETENTION_PERIOD),
        )
        .await;
    // what is the best outcome if "_internal" cannot be created?
    match result {
        Ok(_) => info!("created internal database"),
        Err(err) => {
            match err {
                CatalogError::AlreadyExists => {
                    // this is probably ok
                    debug!("not creating internal db as it exists already");
                }
                _ => {
                    // all other errors are unexpected state
                    error!(?err, "unexpected error when creating internal db");
                    panic!("cannot create internal db");
                }
            }
        }
    };
}

#[derive(Debug, Default)]
pub struct CatalogBuilder {
    catalog_id: Arc<str>,
    object_store: Option<Arc<dyn ObjectStore>>,
    time_provider: Option<Arc<dyn TimeProvider>>,
    metric_registry: Option<Arc<Registry>>,
}

impl CatalogBuilder {
    pub fn catalog_id(mut self, catalog_id: impl Into<Arc<str>>) -> Self {
        self.catalog_id = catalog_id.into();
        self

View on GitHub (pinned to 06200ef96b)