testcontainers/testcontainers-java · error · IllegalArgumentException

Provided Confluent Platform's version

Error message

Provided Confluent Platform's version %s is not supported in Kraft mode (must be %s or above)

What it means

KRaft mode in KafkaContainer requires Confluent Platform version MIN_KRAFT_TAG or newer. verifyMinKraftVersion parses the version part of the Docker image name and throws IllegalArgumentException when it is lower than the minimum supported tag, because older cp-kafka images cannot run in KRaft mode.

Solutions

Upgrade the image to a Confluent Platform version at or above MIN_KRAFT_TAG (e.g. confluentinc/cp-kafka:7.4.0 or newer)
Alternatively, drop withKraft() and use Zookeeper mode for the older image
Check the resolved tag string — ensure it is a real version (e.g. not 'latest' mapped to an old cached image)

Example fix

// before
new KafkaContainer(DockerImageName.parse("confluentinc/cp-kafka:6.2.1")).withKraft();

// after
new KafkaContainer(DockerImageName.parse("confluentinc/cp-kafka:7.4.0")).withKraft();

Defensive patterns

Strategy: validation

Validate before calling

String tag = DockerImageName.parse(imageName).getVersionPart();
if (new ComparableVersion(tag).isLessThan("7.4.0")) {
  throw new IllegalArgumentException(tag + " does not support KRaft; bump the cp-kafka image version");
}

Try / catch

try {
  kafka = new KafkaContainer(IMAGE).withKraft();
} catch (IllegalArgumentException e) {
  if (e.getMessage().contains("not supported in Kraft mode")) {
    kafka = new KafkaContainer(DockerImageName.parse("confluentinc/cp-kafka:7.4.0")).withKraft();
  } else throw e;
}

Prevention

Keep cp-kafka image tags in one constant/property and bump it when adopting withKraft
Check the Confluent Platform KRaft minimum version before enabling KRaft
Avoid floating tags like 'latest' that may resolve to an old cached image
Assert the image version in test setup when parameterizing tags

When it happens

Trigger: Calling withKraft() on a KafkaContainer whose image is an older Confluent Platform tag (e.g. confluentinc/cp-kafka:5.x/6.x, below the required minimum), then verifyMinKraftVersion fails the ComparableVersion check.

Common situations: Upgrading test code to withKraft() while the Docker image tag was left at an older Confluent version; parameterized image versions from CI properties resolving to an old tag; using a Zookeeper-era image like cp-kafka:6.2.1 with KRaft enabled.

Related errors

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

Appendix: source

Thrown at modules/kafka/src/main/java/org/testcontainers/containers/KafkaContainer.java:118

            throw new IllegalStateException("Cannot configure Zookeeper when using Kraft mode");
        }
        this.externalZookeeperConnect = connectString;
        return self();
    }

    public KafkaContainer withKraft() {
        if (this.externalZookeeperConnect != null) {
            throw new IllegalStateException("Cannot configure Kraft mode when Zookeeper configured");
        }
        verifyMinKraftVersion();
        this.kraftEnabled = true;
        return self();
    }

    private void verifyMinKraftVersion() {
        String actualVersion = DockerImageName.parse(getDockerImageName()).getVersionPart();
        if (new ComparableVersion(actualVersion).isLessThan(MIN_KRAFT_TAG)) {
            throw new IllegalArgumentException(
                String.format(
                    "Provided Confluent Platform's version %s is not supported in Kraft mode (must be %s or above)",
                    actualVersion,
                    MIN_KRAFT_TAG
                )
            );
        }
    }

    private boolean isLessThanCP740() {
        String actualVersion = DockerImageName.parse(getDockerImageName()).getVersionPart();
        return new ComparableVersion(actualVersion).isLessThan("7.4.0");
    }

    public KafkaContainer withClusterId(String clusterId) {
        Objects.requireNonNull(clusterId, "clusterId cannot be null");
        getContainerDef().withClusterId(clusterId);
        return self();

View on GitHub (pinned to 8e549514e3)