influxdata/influxdb · error · ValidateDbNameError

invalid character in database or rp name: must be ASCII…

Error message

invalid character in database or rp name: must be ASCII, containing only letters, numbers, underscores, or hyphens

What it means

Variant `InvalidChar` of `ValidateDbNameError` in influxdb3_server/src/http.rs. The requested database (or retention policy) name contains a character outside the allowed set: ASCII letters, numbers, underscores, and hyphens. Names are validated before any database is created or written to.

Solutions

1. Rename the target to only [a-zA-Z0-9_-] characters before sending the request
2. If combining db and retention policy, use the `<db_name>/<rp_name>` form with a forward slash
3. Sanitize/encode the db parameter on the client side with a validation regex before calling the API

Example fix

// before
curl 'host/api/v3/write?db=my data'
// after
curl 'host/api/v3/write?db=my_data'

const DB_RE = /^[a-zA-Z0-9_-]+$/;
function validateDbName(db) {
  if (!DB_RE.test(db)) throw new Error(`invalid db/rp name '${db}': use only ASCII letters, numbers, _ and -`);
}

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

try {
  return await api.write(db, data);
} catch (e) {
  if (String(e.message).includes('invalid character in database or rp name')) {
    throw new ValidationError(`sanitize db name: ${db}`);
  }
  throw e;
}

When it happens

Trigger: Calling write/query endpoints with `?db=` or db/rp path values containing spaces, dots, slashes, Unicode, or symbols (e.g. `db=my data`, `db=my.db`).

Common situations: Deriving database names from user input or filenames; using dots like in v1 'db.rp' notation without the slash form; internationalized names; templated names with unescaped variables.

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.

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• db name did not start with a number or letter
• db name cannot be empty
• db name too long: max
• db name with invalid retention policy, if providing a…
• database name ' ' contains invalid character, character…

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

Appendix: source

Thrown at influxdb3_server/src/http.rs:2422

        }
        last_char.replace(char);
    }

    if last_char.is_some_and(|c| c == '/') {
        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(

View on GitHub (pinned to 06200ef96b)