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

Database name cannot be set to freepdb1

Error message

Database name cannot be set to freepdb1

What it means

OracleContainer.withDatabaseName() rejects the built-in default PDB name (freepdb1, compared case-insensitively) because overriding it with the same value the container already uses by default would be misleading and can conflict with the container's service setup. An IllegalArgumentException naming the reserved value is thrown.

Solutions

1. Choose a distinct custom name, e.g. withDatabaseName("appdb").
2. Remove the withDatabaseName call entirely if the default freepdb1 is what you want.
3. Fix templating so empty/default placeholders don't produce 'freepdb1' as an override.

Example fix

// before
container.withDatabaseName("freepdb1");
// after
container.withDatabaseName("appdb");

if ("freepdb1".equalsIgnoreCase(databaseName)) {
    databaseName = "appdb"; // don't override with the built-in default
}

try {
    container.withDatabaseName(databaseName);
} catch (IllegalArgumentException e) {
    // just don't override; container defaults to freepdb1
}

When it happens

Trigger: Calling withDatabaseName("freepdb1") or any case variant equal to DEFAULT_DATABASE_NAME.

Common situations: Copy-pasting the default PDB name seen in connection logs back into withDatabaseName; templated configs where the default leaks into the override field.

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

• Database name cannot be null or empty
• 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/ac9a640ce3df8a81. Report an issue: GitHub.

Appendix: source

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

    }

    @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)