Docker 이미지 Pull 실패 원인 및 해결 방법 정리

문제 상황

Docker Compose 빌드 중 아래와 같은 오류가 발생했다.

failed to resolve source metadata for docker.io/library/eclipse-temurin:25-jre
failed to do request: Head "https://registry-1.docker.io/v2/library/eclipse-temurin/manifests/25-jre":
dial tcp: lookup registry-1.docker.io on 127.0.0.53:53: server misbehaving

또는 다음과 같은 오류가 발생했다.

failed to resolve reference "docker.io/library/eclipse-temurin:25-jre":
lookup registry-1.docker.io on 127.0.0.53:53: server misbehaving

원인

Dockerfile이나 eclipse-temurin 이미지 문제가 아니었다.

핵심 원인은 Ubuntu의 기본 DNS(systemd-resolved / 127.0.0.53)가 Docker Hub 도메인인 registry-1.docker.io를 정상적으로 조회하지 못한 것이었다.

확인 결과 기본 DNS 조회는 실패했다.

dig registry-1.docker.io

결과:

status: REFUSED
SERVER: 127.0.0.53#53

반면 Google DNS와 Cloudflare DNS로 직접 조회하면 정상적으로 응답했다.

dig @8.8.8.8 registry-1.docker.io
dig @1.1.1.1 registry-1.docker.io

결과:

status: NOERROR
ANSWER SECTION:
registry-1.docker.io. IN A ...

즉, 인터넷 연결이나 Docker Hub 자체의 문제가 아니라 로컬 DNS 설정 문제였다.

해결 방법

1. 현재 DNS 상태 확인

resolvectl status

기본 DNS가 127.0.0.53을 통해 동작하고 있었고, 해당 DNS에서 Docker Hub 주소 조회가 실패하고 있었다.

2. 외부 DNS로 정상 조회되는지 확인

dig @8.8.8.8 registry-1.docker.io
dig @1.1.1.1 registry-1.docker.io

두 명령에서 status: NOERROR와 ANSWER SECTION이 나오면 외부 DNS는 정상이다.

3. systemd-resolved DNS 설정 수정

/etc/systemd/resolved.conf 파일을 수정한다.

sudo nano /etc/systemd/resolved.conf

아래 내용을 설정한다.

[Resolve]
DNS=8.8.8.8 1.1.1.1
FallbackDNS=8.8.4.4 1.0.0.1
DNSStubListener=yes

4. DNS 서비스 및 Docker 재시작

sudo systemctl restart systemd-resolved
sudo resolvectl flush-caches
sudo systemctl restart docker

5. DNS 정상 여부 재확인

dig registry-1.docker.io

정상이라면 아래처럼 나온다.

status: NOERROR
ANSWER SECTION:
registry-1.docker.io. IN A ...

6. Docker Pull 또는 Compose 빌드 재시도

docker pull eclipse-temurin:25-jre

또는

docker compose up -d --build

참고 사항

/etc/docker/daemon.json에 아래처럼 DNS를 설정하는 방법도 시도할 수 있다.

{
  "dns": ["8.8.8.8", "1.1.1.1"]
}

하지만 이 설정은 주로 컨테이너 내부 DNS에 적용된다.
이번 문제처럼 docker pull이나 빌드 메타데이터 조회 단계에서 Docker daemon이 여전히 127.0.0.53을 사용하는 경우에는 OS의 DNS 설정을 먼저 수정해야 한다.

최종 정리

이번 문제의 핵심은 다음과 같다.

dig registry-1.docker.io          → 실패
dig @8.8.8.8 registry-1.docker.io → 성공
dig @1.1.1.1 registry-1.docker.io → 성공
docker pull                       → 실패

따라서 원인은 Dockerfile, Java 버전, eclipse-temurin 이미지 태그 문제가 아니라 Ubuntu 로컬 DNS(systemd-resolved) 문제였다.

해결은 OS DNS를 8.8.8.8, 1.1.1.1 등 정상 동작하는 외부 DNS로 변경한 뒤 systemd-resolved와 Docker를 재시작하는 방식으로 진행했다.