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

Username cannot be one of [system, sys]

Error message

Username cannot be one of [system, sys]

What it means

OracleContainer.withUsername() rejects usernames that match Oracle system users (system, sys, case-insensitively). Testcontainers creates the configured user itself and connecting/creating as a system user is unsupported and would conflict with container initialization, so it throws IllegalArgumentException.

Solutions

1. Use a dedicated application user name, e.g. withUsername("app_user")
2. Remove the override entirely and let the container use its default non-system user
3. If you need system-level access, exec into the running container with docker exec and connect as sys there instead

Example fix

// before
container.withUsername("system");
// after
container.withUsername("app_user");

Set.of("system","sys").contains(user.toLowerCase()) -> reject before calling withUsername

boolean isOracleSystemUser(String u) { return u != null && (u.equalsIgnoreCase("system") || u.equalsIgnoreCase("sys")); }

try { container.withUsername(user); } catch (IllegalArgumentException e) { log.warn("system user rejected, using default"); }

When it happens

Trigger: Calling container.withUsername("system"), withUsername("SYS") or any case variant of a user in ORACLE_SYSTEM_USERS.

Common situations: Copying connection settings from an existing Oracle DB where apps historically logged in as 'system'; defaulting the username from an env var that says 'system'.

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 set to xepdb1
• 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/3cd943f197aa4f20. Report an issue: GitHub.

Appendix: source

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

        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
    public OracleContainer withDatabaseName(String databaseName) {
        if (StringUtils.isEmpty(databaseName)) {
            throw new IllegalArgumentException("Database name cannot be null or empty");

View on GitHub (pinned to 8e549514e3)