EADDRNOTAVAIL 원인과 해결 가이드 (Node.js/Linux)

에러 의미

EADDRNOTAVAIL은 사용할 수 없는 주소/포트를 요청했을 때 발생합니다. 실무에서는 두 경우가 대부분입니다.

• connect EADDRNOTAVAIL: 아웃바운드 포트 고갈
• listen EADDRNOTAVAIL: 존재하지 않는 로컬 IP 바인딩

1) 먼저 분류

로그에서 connect인지 listen인지 먼저 확인합니다. 원인이 완전히 다릅니다.

2) connect 케이스 점검

cat /proc/sys/net/ipv4/ip_local_port_range
ss -tan state time-wait | wc -l

TIME_WAIT 폭증 + 좁은 ephemeral range 조합이면 포트 고갈 가능성이 큽니다.

3) 애플리케이션 대응(우선)

• HTTP keep-alive 활성화
• 요청마다 새 Agent 생성 금지
• 재시도 폭주 방지(백오프 + jitter)
• outbound timeout 명시

4) OS 튜닝(보강)

sudo sysctl -w net.ipv4.ip_local_port_range='1024 65535'

앱 레벨 수정 없이 커널 값만 올리면 재발 가능성이 높습니다.

5) listen 케이스 대응

바인딩 IP를 점검합니다.

• 잘못된 NIC IP 지정 여부
• 컨테이너/호스트 네트워크 모드 불일치

일반적으로 서비스 바인딩은 0.0.0.0 또는 실제 인터페이스 IP를 사용합니다.

요약

EADDRNOTAVAIL은 네트워크 이슈처럼 보이지만, 대부분 연결 관리 정책 문제입니다. connect/listen 분류 -> keep-alive/timeout -> 포트 범위 튜닝 순서로 접근하면 빠르게 수습됩니다.