🚧 [트러블슈팅] Spring Cloud Gateway에서 java.net.UnknownHostException: Failed to resolve 'http:' 오류 해결기 (Mac + Netty + Docker 환경)

✍️ 문제 상황

최근 Spring Cloud Gateway를 사용해 MSA 아키텍처를 구축하던 중, 다음과 같은 이해할 수 없는 네트워크 오류가 발생했습니다

java.net.UnknownHostException: Failed to resolve 'http:' [A(1)]

Gateway에서는 요청을 /auth/login으로 잘 포워딩하려고 하는데, 자꾸 http: 라는 호스트를 찾으려다가 실패하는 DNS 오류가 발생했습니다.

 

⚙️ 환경 구성

• Mac M3 (Apple Silicon)
• Spring Boot 3.x
• Spring Cloud Gateway
• Docker Compose (gateway와 auth 서비스 컨테이너 연결)
• Netty (Spring WebFlux 기본 네트워크 라이브러리)

💥 문제 증상

Gateway 로그:

Route matched: auth-service
Route{id='auth-service', uri=http:/, ...}
java.net.UnknownHostException: Failed to resolve 'http:'

 

• Gateway에서 정상적으로 route가 매칭되지만, Netty가 http: 라는 잘못된 호스트를 해석하려다가 실패함
• auth-service 컨테이너는 정상적으로 8081 포트에서 실행 중이고, gateway에서 forwarding도 시도하고 있었음
• application.yml도 정상적으로 http://auth_service_app:8081 로 작성돼 있었음에도 불구하고 발생

🔍 원인 분석

처음에는 application.yml에서 uri: 설정 문제를 의심했지만...

결국 원인은 Mac M1 환경에서 Netty DNS resolver가 native 라이브러리를 사용하지 못한 데 있었습니다.

Netty는 DNS 조회를 위해 netty-resolver-dns-native-macos라는 네이티브 라이브러리를 사용하는데, 해당 라이브러리가 누락되거나 호환되지 않으면 DNS resolution 자체가 실패합니다.

 

✅ 해결 방법

build.gradle 또는 build.gradle.kts에 다음 의존성을 추가합니다:

runtimeOnly 'io.netty:netty-resolver-dns-native-macos:4.1.104.Final:osx-aarch_64'

 

✅ 이 라이브러리는 M1/M2 Mac (ARM64) 환경에서 Netty가 native DNS 기능을 제대로 사용할 수 있도록 도와줍니다.

dependencies {
    implementation 'org.springframework.cloud:spring-cloud-starter-gateway'
    implementation 'org.springframework.boot:spring-boot-starter-webflux'
    runtimeOnly 'io.netty:netty-resolver-dns-native-macos:4.1.104.Final:osx-aarch_64'
}

✨ 마무리

이 오류는 application.yml 문법 실수처럼 보이기 쉬우나, Mac ARM64 환경에서의 Netty DNS 문제가 원인이었습니다.

이 경험을 통해 알게 된 점은:

• Netty는 내부적으로 DNS resolution을 직접 수행하며, native 라이브러리가 없으면 예상치 못한 에러를 유발할 수 있음
• Spring Cloud Gateway를 M1 환경에서 쓴다면 반드시 해당 라이브러리를 포함시켜야 함
• 에러 메시지가 DNS 관련이라면, 실제로는 URI 파싱이나 네트워크 계층에서의 실패일 수 있음

---

💬 참고

• Netty DNS MacOS ARM64 이슈 GitHub
• Spring Cloud Gateway Docs
• Netty 공식 문서