testcontainers/testcontainers-java · error · java.lang.IllegalArgumentException

Database name cannot be null or empty

Error message

Database name cannot be null or empty

What it means

OracleContainer.withDatabaseName() requires a non-null, non-empty database name. Testcontainers creates this database inside the Oracle instance, so an empty name would produce an invalid CREATE DATABASE/initialization; the library throws IllegalArgumentException up front.

Solutions

1. Supply a real database name, e.g. withDatabaseName("mydb")
2. Fix the config source so the value resolves non-empty
3. Omit withDatabaseName to use the container default database

Example fix

// before
container.withDatabaseName(props.getProperty("db.name"));
// after
String dbName = props.getProperty("db.name", "mydb");
container.withDatabaseName(dbName);

if (dbName == null || dbName.isEmpty()) dbName = "testdb";
container.withDatabaseName(dbName);

boolean isValidDbName(String n) { return n != null && !n.isEmpty(); }

try { container.withDatabaseName(name); } catch (IllegalArgumentException e) { /* omit custom name, use default */ }

When it happens

Trigger: Calling container.withDatabaseName(null) or withDatabaseName("") during container configuration.

Common situations: Database name templated from an unset property; YAML/properties key misspelling; copying config code and forgetting to fill the placeholder.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• Username cannot be null or empty
• Username cannot be one of [system, sys]
• Password cannot be null or empty
• Database name cannot be set to xepdb1
• The number of replicas must be between 0 and 3 (inclusive)

AI-assisted analysis of testcontainers/testcontainers-java@8e549514e3 (2026-09-12). Data as JSON: /api/errors/5ce0f52912be6476. Report an issue: GitHub.

Appendix: source

Thrown at modules/oracle-xe/src/main/java/org/testcontainers/containers/OracleContainer.java:172

            throw new IllegalArgumentException("Username cannot be one of " + ORACLE_SYSTEM_USERS);
        }
        this.username = username;
        return self();
    }

    @Override
    public OracleContainer withPassword(String password) {
        if (StringUtils.isEmpty(password)) {
            throw new IllegalArgumentException("Password cannot be null or empty");
        }
        this.password = password;
        return self();
    }

    @Override
    public OracleContainer withDatabaseName(String databaseName) {
        if (StringUtils.isEmpty(databaseName)) {
            throw new IllegalArgumentException("Database name cannot be null or empty");
        }

        if (DEFAULT_DATABASE_NAME.equals(databaseName.toLowerCase())) {
            throw new IllegalArgumentException("Database name cannot be set to " + DEFAULT_DATABASE_NAME);
        }

        this.databaseName = databaseName;
        return self();
    }

    public OracleContainer usingSid() {
        this.usingSid = true;
        return self();
    }

    @Override
    public OracleContainer withUrlParam(String paramName, String paramValue) {
        throw new UnsupportedOperationException("The Oracle Database driver does not support this");

View on GitHub (pinned to 8e549514e3)