influxdata/influxdb · error · ValidateDbNameError

db name did not start with a number or letter

Error message

db name did not start with a number or letter

What it means

Variant `InvalidStartChar` of `ValidateDbNameError` in influxdb3_server/src/http.rs. The database name's first character must be a letter or a number; names beginning with an underscore, hyphen, or other symbol are rejected during validation.

Solutions

  1. Ensure the name starts with an ASCII letter or digit (e.g. `metrics_tmp` instead of `_metrics`)
  2. Apply a client-side check like `/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/` before sending
  3. Strip leading separators when generating names from templates

Example fix

// before
let db = "_metrics";
// after
let db = "metrics"; // must start with a letter or number
Defensive patterns

Strategy: validation

Validate before calling

function validateDbStart(db) {
  if (!/^[a-zA-Z0-9]/.test(db)) throw new Error(`db name must start with a letter or number: '${db}'`);
}

Type guard

const startsAlphanumeric = (db) => typeof db === 'string' && /^[a-zA-Z0-9]/.test(db);

Try / catch

try {
  return await api.write(db, data);
} catch (e) {
  if (String(e.message).includes('did not start with a number or letter')) {
    throw new ValidationError(`rename '${db}' to start with a letter/digit`);
  }
  throw e;
}

Prevention

When it happens

Trigger: Passing a db name starting with `_`, `-`, or another non-alphanumeric character, e.g. `db=_metrics` or `db=-temp`.

Common situations: Convention-style names with leading underscores copied from other systems (Prometheus-style `_meta`); generated names built by prefixing separators; template placeholders left unresolved (`{{db}}`).

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/1444d7b271a99610. Report an issue: GitHub.

Appendix: source

Thrown at influxdb3_server/src/http.rs:2427

        return Err(ValidateDbNameError::InvalidRetentionPolicy);
    }

    Ok(())
}

// v1 supports 255 chars for the database name and 255 chars for the
// retention policy name; we support those combined with a forward slash so
// 255*2+1.
const MAXIMUM_DATABASE_NAME_LENGTH: usize = 511;

#[derive(Clone, Copy, Debug, thiserror::Error)]
pub enum ValidateDbNameError {
    #[error(
        "invalid character in database or rp name: must be ASCII, \
        containing only letters, numbers, underscores, or hyphens"
    )]
    InvalidChar,
    #[error("db name did not start with a number or letter")]
    InvalidStartChar,
    #[error(
        "db name with invalid retention policy, if providing a \
        retention policy name, must be of form '<db_name>/<rp_name>'"
    )]
    InvalidRetentionPolicy,
    #[error("db name cannot be empty")]
    Empty,
    #[error("db name too long: max {}", MAXIMUM_DATABASE_NAME_LENGTH)]
    NameTooLong,
}

async fn record_batch_stream_to_body(
    mut stream: Pin<Box<dyn RecordBatchStream + Send>>,
    format: QueryFormat,
) -> Result<ResponseBody, Error> {
    match format {
        QueryFormat::Pretty => {

View on GitHub (pinned to 06200ef96b)