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

Database name cannot be set to xepdb1

Error message

Database name cannot be set to xepdb1

What it means

withDatabaseName rejects the value "xepdb1" (case-insensitive). xepdb1 is the default pluggable database name the Oracle XE container creates itself; overriding it would clash with the container's internal setup, so the library throws IllegalArgumentException.

Solutions

1. Choose a different custom database name, e.g. withDatabaseName("mydb")
2. Remove the withDatabaseName call entirely — xepdb1 is already the default
3. If the JDBC URL must reference xepdb1, just use the container's default URL

Example fix

// before
container.withDatabaseName("xepdb1");
// after
container.withDatabaseName("mydb"); // or drop the call

if ("xepdb1".equalsIgnoreCase(dbName)) throw new IllegalArgumentException("xepdb1 is reserved as the default Oracle XE PDB name");

boolean isReservedOracleDbName(String n) { return n != null && "xepdb1".equalsIgnoreCase(n); }

try { container.withDatabaseName(name); } catch (IllegalArgumentException e) { container.withDatabaseName("customdb"); }

When it happens

Trigger: Calling container.withDatabaseName("xepdb1") or withDatabaseName("XEPDB1").

Common situations: Developers seeing the default DB name in the JDBC URL and trying to set it explicitly; migrating config that hardcoded the default from another environment.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Username cannot be one of [system, sys]
• Username cannot be null or empty
• Password cannot be null or empty
• Database name cannot be null or empty
• 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/f8a4cd58c41bc0bd. Report an issue: GitHub.

Appendix: source

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

    }

    @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");
    }

    @SuppressWarnings("SameReturnValue")
    public String getSid() {

View on GitHub (pinned to 8e549514e3)