What causes "invalid database name: {db_name}" in influxdata/influxdb?

Fix the plugin to return only valid database names: non-empty, allowed characters, no leading/trailing whitespace.

influxdata/influxdb · error · anyhow::Error

invalid database name

Error message

invalid database name: {db_name}

What it means

After a WAL plugin runs, its return state may contain writes the plugin wants routed to databases (write_db_lines). Before writing line protocol, each database name is validated with DatabaseName::new. If the plugin returned a database name that is not a valid InfluxDB database identifier, the write is skipped for that entry, an error is recorded, and processing continues with the remaining writes.

Solutions

Fix the plugin to return only valid database names: non-empty, allowed characters, no leading/trailing whitespace.
Validate the database name inside the plugin before adding it to write_db_lines.
Log the plugin return state during development to confirm the exact db_name string produced.
If the name comes from user input or config, sanitize/normalize it before constructing the write.

Example fix

# before
result["write_db_lines"] = {f"{tenant}_{thing}": lines}
# after
from influxdb3 import validate_database_name
name = f"{tenant}_{thing}"
if validate_database_name(name):
    result["write_db_lines"] = {name: lines}
else:
    influxdb3_local.error(f"invalid database name: {name}")

Defensive patterns

Strategy: validation

Validate before calling

def write_to_db(name, lines):
    if not name or any(c in name for c in ' -/\\,.:;!?@#$%^&*()+={}[]|<>"\''):
        raise ValueError(f"invalid database name: {name}")
    result["write_db_lines"] = {name: lines}

Type guard

def is_valid_db_name(name) -> bool:
    return isinstance(name, str) and len(name) > 0 and name == name.strip()

Try / catch

# plugin host records the error per-db and continues; monitor the error stream
for err in run_errors:
    if "invalid database name" in str(err):
        alert(f"plugin emitted bad db name: {err}")

Prevention

Validate database names inside plugins before adding to write_db_lines
Avoid building db names by raw string concatenation of user input
Log plugin return state during development
Use constants for database names instead of dynamic construction

When it happens

Trigger: A plugin's process_writes (or scheduled call) return state includes an entry in write_db_lines whose key is empty, contains invalid characters (spaces, illegal punctuation), or otherwise fails DatabaseName validation when the worker calls write_lp for each (db_name, lines) pair.

Common situations: Python plugin builds the database name by string concatenation (e.g. db = f'{prefix}-{suffix}' producing an empty or malformed name), a mapping/config lookup returns None converted to an invalid string, or a typo in a hardcoded database name.

Understand the failure class

Background: "invalid id" errors: invalid identifier format — why libraries reject IDs before lookup, and how to fix them — this error's family across 37 libraries.

Related errors

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

Appendix: source

Thrown at influxdb3_processing_engine/src/worker/local.rs:617

            error!(error = %ErrorOneLine(error), ?self.trigger_definition, %context, "error running plugin");
        }
    }

    /// Handles the return state from the plugin, writing back lines and handling any errors.
    /// It returns a vec of error messages that can be used to log or report back to the user.
    async fn handle_return_state(
        &self,
        plugin_return_state: influxdb3_py_api::system_py::PluginReturnState,
    ) -> Vec<anyhow::Error> {
        let ingest_time = SystemTime::now()
            .duration_since(SystemTime::UNIX_EPOCH)
            .unwrap();

        let mut errors = Vec::new();

        for (db_name, lines) in plugin_return_state.write_db_lines {
            let Ok(database_name) = DatabaseName::new(db_name.clone()) else {
                errors.push(anyhow!("invalid database name: {db_name}"));
                continue;
            };

            if let Err(e) = self
                .write_endpoint
                .write_lp(
                    WriteTarget::User(database_name),
                    lines.join("\n").as_str(),
                    Time::from_timestamp_nanos(ingest_time.as_nanos() as i64),
                    false,
                )
                .await
                .with_context(|| format!("error writing back lines to {db_name}"))
            {
                errors.push(e);
            }
        }

View on GitHub (pinned to 06200ef96b)