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

Cannot use enterprise version with alternative image

Error message

Cannot use enterprise version with alternative image %s.

What it means

Neo4jContainer.withEnterpriseEdition() only supports upgrading the official Neo4j Docker image to its enterprise tag. If you set a custom/alternative image (e.g. via withImage or a custom docker image name), the container cannot safely derive an enterprise variant, so an IllegalStateException is thrown instead of producing a broken image name.

Solutions

1. Use the default Neo4j image and rely on withEnterpriseEdition() to switch the tag to enterprise.
2. If you need a custom registry, build the full enterprise image name yourself (registry/neo4j:<version>-enterprise) and set it directly instead of calling withEnterpriseEdition().
3. Remove the withEnterpriseEdition() call if you already use a community custom image.

Example fix

// before
new Neo4jContainer<>("my.registry/neo4j:5.12").withEnterpriseEdition();
// after
new Neo4jContainer<>("neo4j:5.12-enterprise");

if (!container.getDockerImageName().startsWith("neo4j:")) {
    throw new IllegalStateException("withEnterpriseEdition() requires the default neo4j image");
}

try {
    container.withEnterpriseEdition();
} catch (IllegalStateException e) {
    // fall back to explicit enterprise image name
    container = new Neo4jContainer<>("neo4j:" + version + "-enterprise");
}

When it happens

Trigger: Calling withEnterpriseEdition() after setting a non-default Docker image (standardImage == false), e.g. container.withImage("mycompany/neo4j").withEnterpriseEdition().

Common situations: Teams pointing at a private registry mirror or custom-built Neo4j image and then trying to enable enterprise features; mixing image customization helpers with withEnterpriseEdition().

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

• Version is not a semantic version. The function…
• This container's image does not have a healthcheck…
• is not a valid Docker image name (in )
• is not a valid image versioning identifier (in )
• anyOthers parameter must be non-empty

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

Appendix: source

Thrown at modules/neo4j/src/main/java/org/testcontainers/containers/Neo4jContainer.java:222

    /**
     * @return URL of the transactional HTTPS endpoint.
     */
    public String getHttpsUrl() {
        return String.format("https://" + getHost() + ":" + getMappedPort(DEFAULT_HTTPS_PORT));
    }

    /**
     * Configures the container to use the enterprise edition of the default docker image.
     * <br><br>
     * Please have a look at the <a href="https://neo4j.com/licensing/">Neo4j Licensing page</a>. While the Neo4j
     * Community Edition can be used for free in your projects under the GPL v3 license, Neo4j Enterprise edition
     * needs either a commercial, education or evaluation license.
     *
     * @return This container.
     */
    public S withEnterpriseEdition() {
        if (!standardImage) {
            throw new IllegalStateException(
                String.format("Cannot use enterprise version with alternative image %s.", getDockerImageName())
            );
        }

        setDockerImageName(DEFAULT_IMAGE_NAME.withTag(ENTERPRISE_TAG).asCanonicalNameString());
        LicenseAcceptance.assertLicenseAccepted(getDockerImageName());

        addEnv("NEO4J_ACCEPT_LICENSE_AGREEMENT", "yes");

        return self();
    }

    /**
     * Sets the admin password for the default account (which is <pre>neo4j</pre>). A null value or an empty string
     * disables authentication.
     *
     * @param adminPassword The admin password for the default database account.
     * @return This container.

View on GitHub (pinned to 8e549514e3)