influxdata/influxdb · error · CatalogError

cannot modify internal db

Error message

cannot modify internal db

What it means

This error is returned when an operation attempts to modify (rename or otherwise alter) an internal database. Like deletion, modification of system-managed databases is forbidden because their schema and naming are invariants of the running system.

Solutions

1. Skip internal/system databases (names beginning with `_`) in modification scripts
2. Verify the target database name before applying changes
3. Use the supported configuration for internal DB behavior instead of direct modification
4. Re-provision the system component if its database must change

Example fix

// before
catalog.rename_database("_internal", "internal_old")?;
// after
if name.starts_with('_') {
    return Err(anyhow!("refusing to modify internal db {name}"));
}
catalog.rename_database(&name, new_name)?;

fn is_internal_db(name: &str) -> bool { name.starts_with('_') }
fn can_modify(name: &str) -> bool { !is_internal_db(name) }

match rename_database(name, new) {
    Err(CatalogError::CannotModifyInternalDatabase) => {/* skip system db */},
    r => r,
}

When it happens

Trigger: Calling database-modification APIs (e.g. rename/update database) against a reserved/internal database name.

Common situations: Migration or refactoring scripts renaming databases wholesale; tools that treat all databases uniformly and attempt schema edits on system DBs.

Understand the failure class

Background: Permission denied / not authorized / 403 Forbidden: access-control rejections when the caller lacks the required role, grant, or ownership — this error's family across 18 libraries.

Related errors

• cannot delete internal db
• Database not found
• database should exist by id
• {0}
• Adding a new database would exceed limit of

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

Appendix: source

Thrown at influxdb3_catalog/src/error.rs:294

    #[error("invalid error behavior {0}")]
    InvalidErrorBehavior(String),

    #[error("cannot parse token permission, {0}")]
    CannotParsePermissionForToken(String),

    #[error("token name already exists, {0}")]
    TokenNameAlreadyExists(String),

    #[error("token hash already exists")]
    TokenHashAlreadyExists,

    #[error("missing admin token, cannot update")]
    MissingAdminTokenToUpdate,

    #[error("cannot delete internal db")]
    CannotDeleteInternalDatabase,

    #[error("cannot modify internal db")]
    CannotModifyInternalDatabase,

    #[error("tried to stop a node ({node_id}) that is already stopped")]
    NodeAlreadyStopped { node_id: Arc<str> },

    #[error(
        "node '{node_id}' is not fully stopped (current state: {current_state}); run \"stop node\" first"
    )]
    NodeNotFullyStopped {
        node_id: Arc<str>,
        current_state: &'static str,
    },

    #[error("node '{node_id}' has compact mode and cannot be removed")]
    NodeModeNotRemovable { node_id: Arc<str> },

    #[error("invalid stop ack for node '{node_id}' (current state: {current_state})")]
    InvalidStopAck {

View on GitHub (pinned to 06200ef96b)