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

You can not activate security on Elastic OSS Image. Please…

Error message

You can not activate security on Elastic OSS Image. Please switch to the default distribution

What it means

ElasticsearchContainer.withPassword throws IllegalArgumentException when the container was created from the Elastic OSS image. The OSS distribution does not support X-Pack security, so setting a password is impossible; the library explicitly rejects it and tells you to use the default (non-OSS) distribution.

Solutions

Switch the DockerImageName to the default distribution, e.g. docker.elastic.co/elasticsearch/elasticsearch:8.x, without the -oss suffix.
If OSS is mandatory, remove the withPassword call and run without authentication.
Assert image choice in test setup so OSS/default mismatch fails early with a clear message.

Example fix

// before
ElasticsearchContainer c = new ElasticsearchContainer(
    DockerImageName.parse("docker.elastic.co/elasticsearch/elasticsearch:7.17.0-oss"))
    .withPassword("secret"); // throws
// after
ElasticsearchContainer c = new ElasticsearchContainer(
    DockerImageName.parse("docker.elastic.co/elasticsearch/elasticsearch:7.17.0"))
    .withPassword("secret");

Defensive patterns

Strategy: validation

Validate before calling

if (imageName.indexOf("-oss") > 0) {
    throw new IllegalArgumentException("OSS image cannot be secured; use the default distribution or drop withPassword");
}
container.withPassword(password);

Try / catch

try {
    container.withPassword(password);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("Elastic OSS Image")) {
        // switch image to the default distribution or remove authentication
    }
    throw e;
}

Prevention

Standardize on the default Elasticsearch distribution for secured test setups.
Centralize image selection in one helper so OSS/default mismatches are caught once.
Document that -oss images cannot use X-Pack security.

When it happens

Trigger: new ElasticsearchContainer(DockerImageName.parse("elasticsearch:7.17.0-oss").asCompatibleSubstituteFor("docker.elastic.co/elasticsearch/elasticsearch")).withPassword("pw") — isOss is true when the image name ends in -oss.

Common situations: Migrating tests from older OSS-based images to secured default images; copying container setup code that sets a password while still pointing at an OSS tag.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

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

Appendix: source

Thrown at modules/elasticsearch/src/main/java/org/testcontainers/elasticsearch/ElasticsearchContainer.java:191

            final SSLContext sslContext = SSLContext.getInstance("TLSv1.3");
            TrustManagerFactory tmfactory = TrustManagerFactory.getInstance(TrustManagerFactory.getDefaultAlgorithm());
            tmfactory.init(trustStore);
            sslContext.init(null, tmfactory.getTrustManagers(), null);
            return sslContext;
        } catch (Exception e) {
            throw new RuntimeException(e);
        }
    }

    /**
     * Define the Elasticsearch password to set. It enables security behind the scene for major version below 8.0.0.
     * It's not possible to use security with the oss image.
     * @param password Password to set
     * @return this
     */
    public ElasticsearchContainer withPassword(String password) {
        if (isOss) {
            throw new IllegalArgumentException(
                "You can not activate security on Elastic OSS Image. Please switch to the default distribution"
            );
        }
        withEnv("ELASTIC_PASSWORD", password);
        if (!isAtLeastMajorVersion8) {
            // major version 8 is secure by default and does not need this to enable authentication
            withEnv("xpack.security.enabled", "true");
        }
        return this;
    }

    /**
     * Configure a CA cert path that is not the default
     *
     * @param certPath Path to the CA certificate within the Docker container to extract it from after start up
     * @return this
     */
    public ElasticsearchContainer withCertPath(String certPath) {

View on GitHub (pinned to 8e549514e3)