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 username before storing it. This library throws IllegalArgumentException when the username is null or empty because Testcontainers needs a valid DB user to create and connect with. It fails fast at configuration time rather than producing a confusing connection failure later.

Solutions

1. Pass a non-null, non-empty username to withUsername, e.g. withUsername("app_user")
2. Fix the source config/env variable so it resolves to a real value before building the container
3. If you don't need a custom user, omit withUsername and use the container's default username

Example fix

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

if (username == null || username.isEmpty()) throw new IllegalArgumentException("DB username must be set");
container.withUsername(username);

boolean isValidUsername(String u) { return u != null && !u.isEmpty(); }

try { container.withUsername(user); } catch (IllegalArgumentException e) { /* fall back to default user */ }

When it happens

Trigger: Calling container.withUsername(null) or withUsername("") (or a whitespace-only string, which StringUtils.isEmpty treats as empty only for null/"") before starting the container.

Common situations: Reading the username from a config file or env var that is unset; passing an Optional-wrapped value unwrapped to null; templating mistakes that yield an empty string.

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
• Database name cannot be null or empty
• Database name cannot be set to xepdb1
• The Oracle Database driver does not support this

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

Appendix: source

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

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