testcontainers/testcontainers-java · error · IllegalStateException

Cannot configure Kraft mode when Zookeeper configured

Error message

Cannot configure Kraft mode when Zookeeper configured

What it means

withKraft() enables KRaft (Zookeeper-less) mode, but if a Zookeeper configuration was already applied via withEmbeddedZookeeper() or withExternalZookeeper(), the settings are mutually exclusive. The method throws IllegalStateException to prevent building a broker config that mixes KRaft with Zookeeper.

Solutions

  1. Remove the preceding withEmbeddedZookeeper()/withExternalZookeeper() calls and keep only withKraft()
  2. Guard the chain with an if/else so only one mode is configured
  3. Start from a clean KafkaContainer instance when switching modes

Example fix

// before
KafkaContainer kafka = new KafkaContainer(DOCKER_IMAGE)
    .withEmbeddedZookeeper()
    .withKraft();

// after
KafkaContainer kafka = new KafkaContainer(DOCKER_IMAGE)
    .withKraft();
Defensive patterns

Strategy: validation

Validate before calling

if (zookeeperConfigured) throw new IllegalStateException("Remove withEmbeddedZookeeper/withExternalZookeeper before calling withKraft()");

Try / catch

try {
  kafka = new KafkaContainer(IMAGE).withEmbeddedZookeeper().withKraft();
} catch (IllegalStateException e) {
  if (e.getMessage().contains("Zookeeper configured")) { kafka = new KafkaContainer(IMAGE).withKraft(); }
  else throw e;
}

Prevention

When it happens

Trigger: Calling kafkaContainer.withEmbeddedZookeeper().withKraft() or kafkaContainer.withExternalZookeeper("zk:2181").withKraft() — any withKraft() call after externalZookeeperConnect/embedded zookeeper was set.

Common situations: Adding withKraft() to an existing Zookeeper-based test setup to 'modernize' it without removing old calls; base test classes that configure Zookeeper while subclasses enable KRaft; copy-pasted fluent chains combining examples.

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/9b1bd8598c8463ed. Report an issue: GitHub.

Appendix: source

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

    public KafkaContainer withEmbeddedZookeeper() {
        if (this.kraftEnabled) {
            throw new IllegalStateException("Cannot configure Zookeeper when using Kraft mode");
        }
        this.externalZookeeperConnect = null;
        return self();
    }

    public KafkaContainer withExternalZookeeper(String connectString) {
        if (this.kraftEnabled) {
            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
                )
            );
        }
    }

View on GitHub (pinned to 8e549514e3)