{"record":{"id":"3e94eef5cd43cfb7","repo":"testcontainers/testcontainers-java","slug":"cannot-configure-zookeeper-when-using-kraft-mode","errorCode":null,"errorMessage":"Cannot configure Zookeeper when using Kraft mode","messagePattern":"Cannot configure Zookeeper when using Kraft mode","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"modules/kafka/src/main/java/org/testcontainers/containers/KafkaContainer.java","lineNumber":92,"sourceCode":"\n    public KafkaContainer(final DockerImageName dockerImageName) {\n        super(dockerImageName);\n        dockerImageName.assertCompatibleWith(DEFAULT_IMAGE_NAME);\n    }\n\n    @Override\n    KafkaContainerDef createContainerDef() {\n        return new KafkaContainerDef();\n    }\n\n    @Override\n    KafkaContainerDef getContainerDef() {\n        return (KafkaContainerDef) super.getContainerDef();\n    }\n\n    public KafkaContainer withEmbeddedZookeeper() {\n        if (this.kraftEnabled) {\n            throw new IllegalStateException(\"Cannot configure Zookeeper when using Kraft mode\");\n        }\n        this.externalZookeeperConnect = null;\n        return self();\n    }\n\n    public KafkaContainer withExternalZookeeper(String connectString) {\n        if (this.kraftEnabled) {\n            throw new IllegalStateException(\"Cannot configure Zookeeper when using Kraft mode\");\n        }\n        this.externalZookeeperConnect = connectString;\n        return self();\n    }\n\n    public KafkaContainer withKraft() {\n        if (this.externalZookeeperConnect != null) {\n            throw new IllegalStateException(\"Cannot configure Kraft mode when Zookeeper configured\");\n        }\n        verifyMinKraftVersion();","sourceCodeStart":74,"sourceCodeEnd":110,"githubUrl":"https://github.com/testcontainers/testcontainers-java/blob/8e549514e3f01c57d70546fbb8599d138f3903e5/modules/kafka/src/main/java/org/testcontainers/containers/KafkaContainer.java#L74-L110","documentation":"KafkaContainer supports either Zookeeper-based or KRaft operation, but not both. withEmbeddedZookeeper() configures the embedded Zookeeper mode, and if KRaft was already enabled via withKraft(), enabling Zookeeper would produce a contradictory broker configuration, so the method throws IllegalStateException immediately.","triggerScenarios":"Calling kafkaContainer.withKraft().withEmbeddedZookeeper() — i.e. any withEmbeddedZookeeper() call after kraftEnabled is true.","commonSituations":"Migrating tests from Zookeeper-based to KRaft mode and keeping old withEmbeddedZookeeper() calls; copy-pasting configuration from different examples; a shared test fixture that sets withKraft() while individual tests also call withEmbeddedZookeeper().","solutions":["Remove the withEmbeddedZookeeper() call when using KRaft mode","Keep only one mode: either withKraft() or (withEmbeddedZookeeper/withExternalZookeeper), never both","If tests need both modes, create separate container instances/builders per mode"],"exampleFix":"// before\nKafkaContainer kafka = new KafkaContainer(DockerImageName.parse(\"confluentinc/cp-kafka:7.4.0\"))\n    .withKraft()\n    .withEmbeddedZookeeper();\n\n// after\nKafkaContainer kafka = new KafkaContainer(DockerImageName.parse(\"confluentinc/cp-kafka:7.4.0\"))\n    .withKraft();","handlingStrategy":"validation","validationCode":"boolean kraft = /* builder flag */;\nif (kraft && usesZookeeper) throw new IllegalStateException(\"Choose either KRaft or Zookeeper, not both\");","typeGuard":null,"tryCatchPattern":"try {\n  kafka = new KafkaContainer(IMAGE).withKraft().withEmbeddedZookeeper();\n} catch (IllegalStateException e) {\n  if (e.getMessage().contains(\"Kraft\")) { kafka = new KafkaContainer(IMAGE).withKraft(); }\n  else throw e;\n}","preventionTips":["Configure exactly one mode per container: withKraft() OR withEmbeddedZookeeper()/withExternalZookeeper()","Centralize Kafka container setup in one factory method","When migrating to KRaft, delete all Zookeeper-related calls","Grep the test codebase for withEmbeddedZookeeper/withExternalZookeeper after enabling withKraft"],"tags":["kafka","kraft","zookeeper","configuration-conflict"],"backgroundTag":"conflicting-config-options","analyzedSha":"8e549514e3f01c57d70546fbb8599d138f3903e5","analyzedAt":"2026-09-12T14:56:41.227Z","contentChangedAt":"2026-09-12T14:56:41.227Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}