TL;DR — 레지스트리에 분명히 있는 이미지가 검증 단계에서 '없음'으로 판정됐다. 매니페스트 조회 Accept에 단일 매니페스트 형식만 넣고 인덱스 형식을 빼먹은 탓이다. 레지스트리는 사유를 명시한 404를 주는데, 클라이언트가 404를 뭉뚱그려 '없음'으로 접었다.

배경

• 프로젝트/기능: DeployHub — 반입 대상 이미지가 실제로 존재하는지, 크기가 얼마인지 확인하는 검증 단계
• 환경: Java 17, Spring Boot 3.5, 레지스트리 REST API

문제 (증상)

• 매니페스트를 분명히 가진 이미지가 검증에서 누락된다
• 반입 목록에서 조용히 빠지므로, 고객사에 가서야 "그 이미지가 없네요"를 알게 된다

원인 분석

• Accept에 단일 매니페스트 2종만 넣고 멀티아키텍처 인덱스 2종을 부럽다
• 레지스트리는 친절하게도 사유를 적어 404를 준다 — "인덱스가 있는데 Accept가 인덱스를 지원하지 않는다"
• 그런데 클라이언트가 404를 전부 Optional.empty()로 돌려 '없음'으로 단정했다
• 즉 협상 실패(406에 가까운 상황)가 도메인 사실('이미지 없음')로 둔갑했다
• 실측 저장소 12개 중 3개가 인덱스였다

해결

• Accept에 인덱스 2종(OCI image index, Docker manifest list)을 추가
• 404의 사유를 구분해 세 갈래로 나눠 판정하도록 고쳤다 — found / 확실히 없음 / 확인 불가(타임아웃·연결 실패·형식 오류)
• '확인 불가'는 없는 것으로 치지 않고 다음 단계에서 재조회하게 두었다
• 인덱스는 자체 layers가 없어 크기 합계가 0이 되므로, 자식 매니페스트를 전부 조회해 합산하도록 함께 고쳤다

결과

• 인덱스 이미지가 더 이상 누락되지 않는다