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

Validation guard in OracleContainer.withDatabaseName: the supplied database name is null or empty (StringUtils.isEmpty), so IllegalArgumentException is thrown. Oracle Free containers require an explicit, non-empty database name for the pluggable database created at startup.

Solutions

1. Pass a non-empty database name, e.g. withDatabaseName("appdb").
2. Fix the config/env source so the value resolves to a real name.
3. Omit the call to keep the container's default database name.

Example fix

// before
container.withDatabaseName(System.getProperty("db.name")); // may be blank
// after
String db = System.getProperty("db.name", "appdb");
container.withDatabaseName(db);

if (databaseName == null || databaseName.trim().isEmpty()) {
    databaseName = "appdb"; // default before calling withDatabaseName
}

try {
    container.withDatabaseName(databaseName);
} catch (IllegalArgumentException e) {
    container.withDatabaseName("appdb");
}

When it happens

Trigger: Calling withDatabaseName(null), withDatabaseName(""), or withDatabaseName(" ").

Common situations: Database name wired from an unset env var or blank config property in CI pipelines.

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

• Database name cannot be set to freepdb1
• Username cannot be null or empty
• Username cannot be one of [system, sys]
• Password cannot be null or empty
• Username cannot be null or empty

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

Appendix: source

Thrown at modules/oracle-free/src/main/java/org/testcontainers/oracle/OracleContainer.java:151

            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)