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

Username cannot be null or empty

Error message

Username cannot be null or empty

What it means

OracleContainer.withUsername() validates the credential before storing it. A null or empty (whitespace-trimmed empty) username is rejected with an IllegalArgumentException because the container cannot construct a valid JDBC connection without one.

Solutions

1. Pass a non-empty username string, e.g. withUsername("app_user").
2. Check the source of the value (env var, system property) before wiring it in.
3. Omit the call entirely to use the container's default username if a default is acceptable.

Example fix

// before
container.withUsername(System.getenv("ORACLE_USER")); // may be null
// after
String user = System.getenv("ORACLE_USER");
if (user == null || user.isEmpty()) { user = "app_user"; }
container.withUsername(user);

if (username == null || username.trim().isEmpty()) {
    username = "app_user"; // default before calling withUsername
}

try {
    container.withUsername(username);
} catch (IllegalArgumentException e) {
    container.withUsername("app_user");
}

When it happens

Trigger: Calling withUsername(null), withUsername(""), or withUsername(" ") on an OracleContainer (oracle-free module).

Common situations: Credential values sourced from environment variables or config files that are unset/empty in CI; property placeholders resolving to blank strings.

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 one of [system, sys]
• Password cannot be null or empty
• Password cannot be null or empty
• Kibana credentials cannot be blank
• Username 'elastic' is reserved for internal use by…

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

Appendix: source

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

    @Override
    public String getPassword() {
        return password;
    }

    @Override
    public String getDatabaseName() {
        return databaseName;
    }

    protected boolean isUsingSid() {
        return usingSid;
    }

    @Override
    public OracleContainer withUsername(String username) {
        if (StringUtils.isEmpty(username)) {
            throw new IllegalArgumentException("Username cannot be null or empty");
        }
        if (ORACLE_SYSTEM_USERS.contains(username.toLowerCase())) {
            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

View on GitHub (pinned to 8e549514e3)