WebClient - io.netty.channel.ConnectTimeoutException

io.netty.channel.ConnectTimeoutException 발생 시점

io.netty.channel.ConnectTimeoutException은 연결을 설정할 수 없을 때 발생하며, 연결 타임아웃으로 인해 발생하는 ConnectException입니다.
더 정확하게는 ChannelOption.CONNECT_TIMEOUT_MILLIS 옵션으로 설정한 시간 내에 서버와의 TCP 연결이 수립되지 않을 때 발생합니다.

---

발생 시점 

WebClient 요청 시작
  ↓
[ChannelOption.CONNECT_TIMEOUT_MILLIS 설정 시간]
  ↓ (3초 경과)
→ io.netty.channel.ConnectTimeoutException 발생

 

# 서버와의 TCP 핸드셰이크 실패

javaHttpClient httpClient = HttpClient.create()
    .option(ChannelOption.CONNECT_TIMEOUT_MILLIS, 3000);  // 3초

WebClient webClient = WebClient.builder()
    .clientConnector(new ReactorClientHttpConnector(httpClient))
    .build();

---

발생 유형

1. 서버가 없는 경우

webClient.get().uri("https://non-existent-server.com:443")
→ 3초 대기 후 ConnectTimeoutException 발생

 

2. 서버가 응답하지 않는 경우

webClient.get().uri("https://unreachable-server.com:443")
→ 3초 대기 후 ConnectTimeoutException 발생

3. 네트워크 지연

webClient.get().uri("https://slow-network.com:443")
→ 3초 이상 걸리면 ConnectTimeoutException 발생

---

Catch 방법

javaimport io.netty.channel.ConnectTimeoutException;

webClient.get()
    .uri("https://...")
    .retrieve()
    .bodyToFlux(String.class)
    .onErrorResume(ConnectTimeoutException.class, ex -> {
        logger.error("ConnectTimeoutException: {}", ex.getMessage());
        return Flux.empty();
    })
    .subscribe();

---

타임아웃 발생 순서

요청 시작
  ↓
[CONNECT_TIMEOUT_MILLIS: 3초] ← io.netty.channel.ConnectTimeoutException
  ↓ (연결 성공)
[ReadTimeoutHandler: 10초] ← io.netty.handler.timeout.ReadTimeoutException
  ↓ (데이터 수신)
[responseTimeout: 15초] ← ReadTimeoutException (또는 wrap됨)

---

결론

io.netty.channel.ConnectTimeoutException은 TCP 연결 수립 단계에서 발생합니다.
ChannelOption.CONNECT_TIMEOUT_MILLIS 초과 시 발생하면 가장 먼저 발생할 수 있는 타임아웃입니다.