기술 · 실용 가이드

Docker pull의 manifest unknown? 삭제 전에 원격 reference를 증명하세요

확장된 registry, repository, tag 또는 digest를 보존하고 remote descriptor와 인증 view를 확인합니다.

작성 Watch at Ease News · 4 분 읽기발행 2026. 10. 16. 오전 11:20 UTC

manifest unknown은 local cache 일반 오류가 아니라 registry의 name/tag 조회 결과입니다.

reference, descriptor, platform, runtime을 분리해 확인하세요.

확장된 reference 보존

전체 오류와 실제 실행된 명령, Compose 서비스 또는 배포 필드를 복사합니다. registry 호스트, namespace, repository, tag 또는 digest를 기록하고 변경하기 전에 CI 변수를 출력합니다.

먼저 image를 prune하거나 builder cache를 지우지 마세요. MANIFEST_UNKNOWN은 요청한 원격 이름과 tag에 대한 registry 응답이며, 로컬 layer를 삭제해도 원격 manifest는 생기지 않습니다.

reference를 registry, repository 경로, image 이름, tag 네 부분으로 나눕니다. tag를 생략하면 보통 latest를 요청하지만, repository가 있어도 latest가 게시되어 있다는 뜻은 아닙니다.

대소문자, 구분자, CI 치환 결과를 문자 단위로 비교합니다. login 성공이나 다른 tag의 존재는 일부 내용에 접근할 수 있음을 보여줄 뿐, 이 exact reference의 존재를 증명하지 않습니다.

registry UI 또는 인증된 manifest inspection 명령으로 정확한 tag를 조회하고 반환된 digest와 media type을 기록합니다. tag가 없다면 실제 immutable tag를 선택하거나 게시 과정을 수정합니다.

digest가 이미 고정되어 있으면 그 digest를 직접 조회합니다. tag는 이동할 수 있지만 digest는 content-addressed이므로 따로 검사하고 실패한 reference를 사고 기록에 남깁니다.

tag가 image index로 해석되면 필요한 OS와 architecture descriptor가 있는지 확인합니다. tag는 있지만 platform이 없는 경우는 name/tag의 MANIFEST_UNKNOWN과 다른 분기입니다.

amd64가 성공한다고 arm64나 Windows variant도 있다고 가정하지 마세요. workload에 맞을 때만 누락된 variant를 게시하거나 지원 tag를 선택하거나 target platform을 바꿉니다.

대화형 환경에서는 되지만 CI에서 실패하면 확장된 문자열, credential, registry hostname, proxy, network path를 비교합니다. mirror나 pull-through cache는 origin과 다른 view를 보일 수 있습니다.

마지막으로 실패했던 동일 runtime과 registry 경로에서 정확한 tag 또는 digest가 해석됨을 증명합니다. descriptor digest와 platform을 기록하고 재현성이 중요하면 immutable reference를 고정합니다.