What causes "Empty password can be used only with the root user" in testcontainers/testcontainers-java?

Call .withPassword("some-password") on the container builder

testcontainers/testcontainers-java · error · ContainerLaunchException

Empty password can be used only with the root user

Error message

Empty password can be used only with the root user

What it means

MariaDBContainer.configure() validates credentials when building the container environment. If no password is set, an empty-password database is only allowed for the root user (MYSQL_ALLOW_EMPTY_PASSWORD). For any other username it throws ContainerLaunchException, because MariaDB images refuse empty passwords for non-root users.

Solutions

Call .withPassword("some-password") on the container builder
Or use the root user via .withUsername("root") if you intentionally want an empty password
Or set the password from configuration/properties instead of hardcoding an empty value

Example fix

// before
MariaDBContainer mariadb = new MariaDBContainer("mariadb:10.6")
    .withUsername("appuser"); // empty password, non-root -> throws
// after
MariaDBContainer mariadb = new MariaDBContainer("mariadb:10.6")
    .withUsername("appuser")
    .withPassword("testpassword");

Defensive patterns

Strategy: validation

Validate before calling

// before start()
Objects.requireNonNull(container.getUsername());
if (container.getUsername() != null && !"root".equalsIgnoreCase(container.getUsername())
        && (password == null || password.isEmpty())) {
    throw new IllegalArgumentException("MariaDBContainer requires a password for non-root users");
}

Try / catch

try {
    mariadb.start();
} catch (ContainerLaunchException e) {
    if (e.getMessage().contains("Empty password")) {
        throw new IllegalStateException("Set withPassword() or use username 'root'", e);
    }
    throw e;
}

Prevention

Always pair withUsername() with withPassword() in shared fixtures
Never pass empty strings to withPassword()
Centralize container creation in a factory that enforces credentials

When it happens

Trigger: Constructing new MariaDBContainer(...) without calling withPassword(...) (or calling withPassword("") ) while withUsername(...) is set to a non-root user such as 'test', then starting the container.

Common situations: Copy-pasted container setup where the username was customized but the password line was dropped; relying on a default empty password after a library version change; YAML/properties-driven config where the password key is missing.

Related errors

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

Appendix: source

Thrown at modules/mariadb/src/main/java/org/testcontainers/containers/MariaDBContainer.java:83

        optionallyMapResourceParameterAsVolume(
            MY_CNF_CONFIG_OVERRIDE_PARAM_NAME,
            "/etc/mysql/conf.d",
            "mariadb-default-conf",
            Transferable.DEFAULT_DIR_MODE
        );

        addEnv("MYSQL_DATABASE", databaseName);

        if (!MARIADB_ROOT_USER.equalsIgnoreCase(this.username)) {
            addEnv("MYSQL_USER", username);
        }
        if (password != null && !password.isEmpty()) {
            addEnv("MYSQL_PASSWORD", password);
            addEnv("MYSQL_ROOT_PASSWORD", password);
        } else if (MARIADB_ROOT_USER.equalsIgnoreCase(username)) {
            addEnv("MYSQL_ALLOW_EMPTY_PASSWORD", "yes");
        } else {
            throw new ContainerLaunchException("Empty password can be used only with the root user");
        }
        setStartupAttempts(3);
    }

    @Override
    public String getDriverClassName() {
        return "org.mariadb.jdbc.Driver";
    }

    @Override
    public String getJdbcUrl() {
        String additionalUrlParams = constructUrlParameters("?", "&");
        return (
            "jdbc:mariadb://" + getHost() + ":" + getMappedPort(MARIADB_PORT) + "/" + databaseName + additionalUrlParams
        );
    }

    @Override

View on GitHub (pinned to 8e549514e3)