apache/dolphinscheduler · error · IllegalArgumentException

database name illegal

Error message

database name illegal

What it means

Generic validation guard in AbstractDataSourceProcessor.checkDatabasePatter: fires when the database name does not match DATABASE_PATTER (identifier charset pattern), meaning the supplied database name contains illegal characters or is empty.

Source

Thrown at dolphinscheduler-datasource-plugin/dolphinscheduler-datasource-api/src/main/java/org/apache/dolphinscheduler/plugin/datasource/api/datasource/AbstractDataSourceProcessor.java:85

     * Check the host is valid
     *
     * @param host datasource host
     */
    protected void checkHost(String host) {
        if (com.google.common.net.InetAddresses.isInetAddress(host)) {
        } else if (!IPV4_PATTERN.matcher(host).matches() || !IPV6_PATTERN.matcher(host).matches()) {
            throw new IllegalArgumentException("datasource host illegal");
        }
    }

    /**
     * check database name is valid
     *
     * @param database database name
     */
    protected void checkDatabasePatter(String database) {
        if (!DATABASE_PATTER.matcher(database).matches()) {
            throw new IllegalArgumentException("database name illegal");
        }
    }

    /**
     * check other is valid
     *
     * @param other other
     */
    protected void checkOther(Map<String, String> other) {
        if (MapUtils.isEmpty(other)) {
            return;
        }

        if (!Sets.intersection(other.keySet(), POSSIBLE_MALICIOUS_KEYS).isEmpty()) {
            throw new IllegalArgumentException("Other params include possible malicious keys.");
        }

        for (Map.Entry<String, String> entry : other.entrySet()) {

View on GitHub (pinned to 02eac45a1b)

Solutions

1. Use only [a-zA-Z0-9_-] style characters allowed by DATABASE_PATTER
2. Rename or quote the database at the DB level and reference the compliant name
3. Check for accidental whitespace when pasting the database name

Example fix

// before
param.setDatabase("my-db.v2");
// after
param.setDatabase("my_db_v2");

boolean dbOk = database != null && database.matches("^[a-zA-Z0-9_]+$");

try { dto.setDatabase(name); processor.checkDatasourceParam(dto); } catch (IllegalArgumentException e) { /* surface 'database name illegal' to user */ }

When it happens

Trigger: Creating/updating a datasource whose database field contains illegal characters (dashes, dots, spaces, special chars) or is empty.

Common situations: Database names with hyphens (common in cloud providers), names copied with trailing spaces, schema-qualified names like 'db.schema'.

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

• 1400004
• spark datasource param is not valid
• datasource host illegal
• datasource other params: + entry.getKey() + illegal
• address is null.

AI-assisted analysis of apache/dolphinscheduler@02eac45a1b (2026-09-06). Data as JSON: /api/errors/71d83f73b0201096. Report an issue: GitHub.