{
  "id": "kafka/network-exception-connection-refused",
  "signature": "java.net.ConnectException: Connection refused (Connection refused) at org.apache.kafka.clients.NetworkClient",
  "signature_zh": "java.net.ConnectException: 连接被拒绝（Connection refused）在org.apache.kafka.clients.NetworkClient",
  "regex": "java\\.net\\.ConnectException: Connection refused.*NetworkClient",
  "domain": "kafka",
  "category": "network_error",
  "subcategory": null,
  "root_cause": "Kafka client cannot establish a TCP connection to the broker because the broker port is not listening or a firewall is blocking the port.",
  "root_cause_type": "generic",
  "root_cause_zh": "Kafka客户端无法与代理建立TCP连接，因为代理端口未监听或防火墙阻止了该端口。",
  "versions": [
    {
      "version": "Kafka 3.0.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "Kafka 3.1.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "Kafka 3.2.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "Kafka 3.5.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    }
  ],
  "os_specific": {},
  "dead_ends": [
    {
      "action": "Change advertised.listeners to localhost",
      "why_fails": "If broker is on a different host, localhost prevents external connections; the issue is port, not hostname.",
      "fail_rate": 0.8,
      "condition": "",
      "sources": []
    },
    {
      "action": "Increase request.timeout.ms in client config",
      "why_fails": "Timeout does not fix connection refusal; the TCP handshake fails immediately.",
      "fail_rate": 0.95,
      "condition": "",
      "sources": []
    },
    {
      "action": "Disable SSL/TLS in broker config",
      "why_fails": "If broker expects SSL, disabling it causes auth errors; connection refusal is often port-based.",
      "fail_rate": 0.6,
      "condition": "",
      "sources": []
    }
  ],
  "workarounds": [
    {
      "action": "Verify broker is listening on the correct port and address.\nCommand:\nnetstat -tlnp | grep 9092\n# Should show LISTEN with Kafka process\n# If not, check broker logs:\ngrep -i 'listener' /var/log/kafka/server.log\n# Ensure listeners=PLAINTEXT://0.0.0.0:9092 in server.properties\n# Restart broker:\nkafka-server-stop.sh && kafka-server-start.sh -daemon config/server.properties",
      "success_rate": 0.95,
      "how": "Verify broker is listening on the correct port and address.\nCommand:\nnetstat -tlnp | grep 9092\n# Should show LISTEN with Kafka process\n# If not, check broker logs:\ngrep -i 'listener' /var/log/kafka/server.log\n# Ensure listeners=PLAINTEXT://0.0.0.0:9092 in server.properties\n# Restart broker:\nkafka-server-stop.sh && kafka-server-start.sh -daemon config/server.properties",
      "condition": "",
      "sources": []
    },
    {
      "action": "Check firewall rules and allow inbound traffic on port 9092.\nCommand:\nsudo ufw status | grep 9092\n# If not allowed:\nsudo ufw allow 9092/tcp\n# For iptables:\niptables -A INPUT -p tcp --dport 9092 -j ACCEPT\n# Test connectivity from client:\ntelnet broker-host 9092",
      "success_rate": 0.93,
      "how": "Check firewall rules and allow inbound traffic on port 9092.\nCommand:\nsudo ufw status | grep 9092\n# If not allowed:\nsudo ufw allow 9092/tcp\n# For iptables:\niptables -A INPUT -p tcp --dport 9092 -j ACCEPT\n# Test connectivity from client:\ntelnet broker-host 9092",
      "condition": "",
      "sources": []
    }
  ],
  "workarounds_zh": [
    "Verify broker is listening on the correct port and address.\nCommand:\nnetstat -tlnp | grep 9092\n# Should show LISTEN with Kafka process\n# If not, check broker logs:\ngrep -i 'listener' /var/log/kafka/server.log\n# Ensure listeners=PLAINTEXT://0.0.0.0:9092 in server.properties\n# Restart broker:\nkafka-server-stop.sh && kafka-server-start.sh -daemon config/server.properties",
    "Check firewall rules and allow inbound traffic on port 9092.\nCommand:\nsudo ufw status | grep 9092\n# If not allowed:\nsudo ufw allow 9092/tcp\n# For iptables:\niptables -A INPUT -p tcp --dport 9092 -j ACCEPT\n# Test connectivity from client:\ntelnet broker-host 9092"
  ],
  "transition_graph": {
    "leads_to": [],
    "preceded_by": [],
    "frequently_confused_with": []
  },
  "official_doc_url": "https://kafka.apache.org/documentation/#brokerconfigs_listeners",
  "official_doc_section": null,
  "error_code": null,
  "verification_tier": "ai_generated",
  "confidence": 0.9,
  "fix_success_rate": 0.95,
  "resolvable": "true",
  "first_seen": "2023-06-01",
  "last_confirmed": "2024-06-01",
  "last_updated": "2024-06-01",
  "evidence_count": 1,
  "tags": [],
  "locale": "en",
  "aliases": []
}