Kafka ERROR org.apache.kafka.common.errors.TimeoutException:

로컬 환경에서 Kafka TimeoutException이 발생할 때, 체계적으로 점검해야 할 핵심 절차는 다음과 같습니다. 서비스 상태 → 네트워크 → 설정 → 리소스 → 클라이언트 순으로 진단하는 것이 효율적입니다.

---

1. Kafka/Zookeeper 서비스 정상 동작 여부 확인

bash

Copy

# 1) 프로세스 실행 확인
jps | grep -E "Kafka|Quorum"

# 2) Kafka broker 상태 확인 (로컬 토픽 리스트 조회)
bin/kafka-topics.sh --list --bootstrap-server localhost:9092

# 3) Zookeeper 연결 확인 (Zookeeper를 사용하는 경우)
echo ruok | nc localhost 2181  # 응답: imok

점검 포인트:

• Broker가 완전히 시작되기 전에 클라이언트가 연결 시도했는지
• 로그 파일(logs/server.log)에 STARTED 메시지가 있는지 확인

---

2. 네트워크 및 포트 연결성 점검

bash

Copy

# Kafka 기본 포트(9092) 리스닝 확인
netstat -an | grep 9092

# telnet으로 연결 테스트
telnet localhost 9092

# Docker를 사용 중이라면 포트 포워딩 확인
docker ps | grep 9092

점검 포트:

• 방화벽 또는 보안 그룹에 의해 포트가 차단되지 않았는지
• localhost 대신 127.0.0.1을 명시적으로 사용해 보세요 (IPv6 이슈 방지)

---

3. Kafka Broker 핵심 설정 검증

config/server.properties 파일을 확인하세요:

properties

Copy

# 가장 중요: 로컬 테스트 환경에서는 이 설정이 주요 원인입니다
listeners=PLAINTEXT://localhost:9092
advertised.listeners=PLAINTEXT://localhost:9092

# Docker 환경에서는 호스트 IP를 명시해야 할 수 있습니다
# advertised.listeners=PLAINTEXT://{YOUR_HOST_IP}:9092

점검 포인트:

• advertised.listeners가 클라이언트가 접근 가능한 주소로 설정되어 있는지
• 클라이언트의 bootstrap.servers와 일치하는지

---

4. 클라이언트 설정 점검

Producer/Consumer 코드의 설정을 확인하세요:

java

Copy

// 필수 최소 설정
props.put("bootstrap.servers", "localhost:9092");
props.put("request.timeout.ms", "30000");  // 기본 30초, 로컬에선 10초로 줄여도 됨
props.put("retry.backoff.ms", "1000");

// 테스트용으로 적절한 타임아웃 설정
props.put("max.block.ms", "5000");  // 메시지 전송 블록 최대 시간

점검 포인트:

• bootstrap.servers가 Broker의 advertised.listeners와 정확히 일치하는지
• 타임아웃 값이 너무 짧게 설정되지 않았는지 (로컬이더라도 초기 연결에는 시간 필요)

---

5. 토픽 상태 확인

bash

Copy

# 토픽 존재 여부 및 상태 확인
bin/kafka-topics.sh --describe --topic your-topic --bootstrap-server localhost:9092

# 토픽이 없다면 생성
bin/kafka-topics.sh --create --topic your-topic --partitions 1 --replication-factor 1 --bootstrap-server localhost:9092

점검 포인트:

• 토픽이 존재하지 않으면 auto.create.topics.enable=true 설정 확인
• 파티션 리더가 없는 경우 (Leader: -1)는 Broker 간 문제

---

6. 리소스 및 임시 파일 정리

bash

Copy

# 로컬 환경에서 자주 발생: 잘못된 종료로 인한 잠금 파일
rm -rf /tmp/kafka-logs/*      # Kafka 데이터 로그
rm -rf /tmp/zookeeper/*       # Zookeeper 데이터 (Zookeeper 사용 시)

# Zookeeper가 깨끗한 상태로 시작되도록
echo "1" > /tmp/zookeeper/myid  # (Zookeeper 클러스터 설정 시)

점검 포인트:

• 이전 테스트의 깨진 세션이 남아있지 않은지
• 디스크 여유 공간 확인 (df -h)

---

7. 로그 분석

bash

Copy

# Kafka Broker 로그 실시간 모니터링
tail -f logs/server.log | grep ERROR

# 주요 에러 패턴
# - "Unable to resolve address": listeners 설정 오류
# - "Connection refused": 포트 미개방 또는 서비스 미실행
# - "LEADER_NOT_AVAILABLE": 토픽 생성 대기 필요

---

8. 로컬 환경 특수 상황 대응

Docker Compose 사용 시

yaml

Copy

# docker-compose.yml 예시
services:
  kafka:
    environment:
      KAFKA_ADVERTISED_LISTENERS: PLAINTEXT://localhost:9092  # 호스트에서 접속 시
      # 또는 PLAINTEXT://kafka:9092 (컨테이너 내부 통신 시)

Windows 환경

• WSL2를 사용 중이라면, Windows 방화벽이 포트를 차단하지 않는지 확인
• localhost 대신 host.docker.internal 사용 검토

---

9. 재현 테스트 절차

문제를 최소화된 코드로 재현해보세요:

bash

Copy

# 1) Console Producer 테스트
bin/kafka-console-producer.sh --topic test-topic --bootstrap-server localhost:9092

# 2) Console Consumer 테스트 (새 터미널)
bin/kafka-console-consumer.sh --topic test-topic --bootstrap-server localhost:9092 --from-beginning

# 3) 성공 시 클라이언트 코드 문제, 실패 시 Broker/네트워크 문제

---

체크리스트 요약

Table

Copy

순서항목명령어/확인 사항

1	서비스 실행	jps, kafka-topics.sh --list
2	포트 연결	telnet localhost 9092
3	Broker 설정	listeners, advertised.listeners 일치
4	클라이언트 설정	bootstrap.servers 정확성
5	토픽 존재	kafka-topics.sh --describe
6	임시 파일	/tmp/kafka-logs 삭제
7	로그 분석	logs/server.log의 ERROR

90%의 로컬 TimeoutException은 advertised.listeners 설정 불일치 또는 Broker 미실행이 원인입니다. 이 두 가지를 먼저 확인하시면 빠르게 해결될 것입니다.