{"record":{"id":"01be995a1299a2fc","repo":"apache/kafka","slug":"you-cannot-set-both-bootstrap-servers-and-bootstra","errorCode":null,"errorMessage":"You cannot set both bootstrap.servers and bootstrap.controllers","messagePattern":"You cannot set both bootstrap\\.servers and bootstrap\\.controllers","errorType":"validation","errorClass":"ConfigException","httpStatus":null,"severity":"error","filePath":"clients/src/main/java/org/apache/kafka/clients/admin/KafkaAdminClient.java","lineNumber":554,"sourceCode":"        }\n        List<String> controllerServers = config.getList(AdminClientConfig.BOOTSTRAP_CONTROLLERS_CONFIG);\n        if (controllerServers == null) {\n            controllerServers = Collections.emptyList();\n        }\n\n        if (bootstrapServers.isEmpty()) {\n            if (controllerServers.isEmpty()) {\n                throw new ConfigException(\"You must set either \" +\n                    CommonClientConfigs.BOOTSTRAP_SERVERS_CONFIG + \" or \" +\n                    AdminClientConfig.BOOTSTRAP_CONTROLLERS_CONFIG);\n            } else {\n                return true; // Using bootstrap.controllers\n            }\n        } else {\n            if (controllerServers.isEmpty()) {\n                return false; // Using bootstrap.servers\n            } else {\n                throw new ConfigException(\"You cannot set both \" +\n                    CommonClientConfigs.BOOTSTRAP_SERVERS_CONFIG + \" and \" +\n                    AdminClientConfig.BOOTSTRAP_CONTROLLERS_CONFIG);\n            }\n        }\n    }\n\n    static KafkaAdminClient createInternal(AdminClientConfig config, TimeoutProcessorFactory timeoutProcessorFactory) {\n        return createInternal(config, timeoutProcessorFactory, null);\n    }\n\n    static KafkaAdminClient createInternal(\n        AdminClientConfig config,\n        TimeoutProcessorFactory timeoutProcessorFactory,\n        HostResolver hostResolver\n    ) {\n        Metrics metrics = null;\n        NetworkClient networkClient = null;\n        Time time = Time.SYSTEM;","sourceCodeStart":536,"sourceCodeEnd":572,"githubUrl":"https://github.com/apache/kafka/blob/996fb4585aa1bcc8980b0e1b8d6b168b986cd979/clients/src/main/java/org/apache/kafka/clients/admin/KafkaAdminClient.java#L536-L572","documentation":"Thrown by KafkaAdminClient.determineBootstrapType (a ConfigException) when both bootstrap.servers and bootstrap.controllers are set. The two are mutually exclusive: one targets brokers, the other targets KRaft controllers, and the client cannot decide which to use.","triggerScenarios":"A config map containing both CommonClientConfigs.BOOTSTRAP_SERVERS_CONFIG and AdminClientConfig.BOOTSTRAP_CONTROLLERS_CONFIG with non-empty values. Merging a base config (with bootstrap.servers) with an overlay (with bootstrap.controllers) without clearing the other.","commonSituations":"Switching a deployment from broker bootstrap to controller bootstrap but leaving the old property in the config file; shared config template that sets both 'just in case'; environment-specific overrides layered on top of defaults.","solutions":["Pick one mode: keep bootstrap.servers for normal Admin usage, or bootstrap.controllers for direct controller access, and remove the other.","When layering configs, explicitly null/remove the key you are not using.","Validate the config map programmatically: assert exactly one of the two keys is non-empty."],"exampleFix":"// before\nprops.put(\"bootstrap.servers\", \"broker:9092\");\nprops.put(\"bootstrap.controllers\", \"ctrl:9093\");\n\n// after (broker mode)\nprops.put(\"bootstrap.servers\", \"broker:9092\");\nprops.remove(\"bootstrap.controllers\");","handlingStrategy":"validation","validationCode":"boolean hasServers = props.containsKey(AdminClientConfig.BOOTSTRAP_SERVERS_CONFIG)\n    && !((String) props.get(AdminClientConfig.BOOTSTRAP_SERVERS_CONFIG)).isEmpty();\nboolean hasControllers = props.containsKey(AdminClientConfig.BOOTSTRAP_CONTROLLERS_CONFIG)\n    && !((String) props.get(AdminClientConfig.BOOTSTRAP_CONTROLLERS_CONFIG)).isEmpty();\nif (hasServers && hasControllers) {\n    throw new IllegalStateException(\"Set exactly one of bootstrap.servers / bootstrap.controllers\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    Admin.create(props);\n} catch (ConfigException e) {\n    if (e.getMessage().contains(\"cannot set both\")) {\n        props.remove(AdminClientConfig.BOOTSTRAP_CONTROLLERS_CONFIG);\n        Admin.create(props);\n    }\n}","preventionTips":["Pick one bootstrap mode per environment and remove the other key.","When layering configs, explicitly null the key you are not using."],"tags":["kafka-admin","configuration","bootstrap","client-setup"],"backgroundTag":null,"analyzedSha":"996fb4585aa1bcc8980b0e1b8d6b168b986cd979","analyzedAt":"2026-08-11T22:03:28.655Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}