Docker invalid reference format 해결: 이미지 이름과 셸 인수를 구분해 점검

 

직접 생성한 개념 이미지입니다. 실제 서비스 화면이나 구축·성능 시험 결과가 아닙니다.

invalid reference format은 먼저 Docker가 IMAGE 인수로 무엇을 받았는지 확인해야 하는 오류입니다. 저장소 이름 문법이 틀렸을 수도 있지만, 따옴표가 빠진 경로나 빈 변수 때문에 다른 문자열이 이미지로 해석될 수도 있습니다. 이미지 전체를 무조건 소문자로 바꾸거나 다시 빌드하기 전에 인수 경계를 확인하세요.

원인: 이미지 참조의 문법 오류와 인수 위치 오류가 같은 메시지로 보일 수 있다

docker run은 옵션 다음에 이미지 인수를 받고 그 뒤에 컨테이너 명령과 인수를 받습니다. 옵션 값이 공백에서 잘리면 예상하지 않은 조각이 IMAGE 자리에 놓일 수 있습니다. 이 단계에서 실패했다면 애플리케이션 로그나 컨테이너 네트워크부터 수정하는 것은 원인과 맞지 않을 수 있습니다.

관찰	먼저 확인	피할 조치
저장소에 대문자	경로 부분 문법	태그까지 일괄 변경
공백 경로 사용	따옴표와 인수 경계	파일 삭제·재빌드
CI에서만 실패	셸·변수 범위	환경 변수 전체 공개
오류 문구 변경	새 실패 단계	원인 없이 반복 실행

1. 명령을 한 줄로 줄이고 IMAGE 자리를 표시한다

아래 구조에서 대괄호는 설명용입니다. 그대로 입력하는 문자가 아닙니다. 실제 실행 전에 옵션과 값이 쌍을 이루는지 확인하고 IMAGE 뒤에 둔 Docker 옵션이 컨테이너 명령으로 넘어가지 않았는지도 봅니다.

docker run [OPTIONS] IMAGE [COMMAND] [ARG...]
# 이미지 참조 형식의 예시 — 실행 명령 아님
registry.example/team/api:Release_1

여러 줄 명령은 사용한 셸의 이어쓰기 문법을 확인합니다. Bash의 역슬래시, PowerShell의 백틱, cmd의 캐럿을 섞지 마세요. 먼저 한 줄로 정리하면 눈에 보이지 않는 이어쓰기 문제와 이미지 문법 문제를 분리하기 쉽습니다. 웹 문서의 곡선 따옴표도 일반 따옴표와 같게 해석된다고 가정하지 않습니다.

2. 저장소 경로와 태그의 규칙을 분리한다

registry.example/team/api:Release_1에서 team/api는 저장소 경로, Release_1은 태그입니다. 저장소 경로에는 소문자 제약이 있지만 태그에는 대문자가 허용될 수 있습니다. 따라서 태그까지 소문자로 바꾸면 원래 배포하려던 이미지와 다른 참조가 되거나 존재하지 않는 태그를 요청할 수 있습니다.

레지스트리 주소 앞에 https://를 붙이는 것도 이미지 참조 문법과 다릅니다. 포트가 있으면 호스트 뒤에 두고, 태그의 콜론과 혼동하지 않도록 전체 문자열을 점검합니다. 이름을 바로잡는 과정에서 의도한 레지스트리·팀·프로젝트·태그가 유지되는지 배포 설정과 대조하세요.

3. 변수는 실행 전에 비어 있지 않은지 확인한다

다음은 Bash에서 비밀값이 아닌 이미지 이름 변수를 확인하는 예시입니다. 전체 환경 변수를 출력하지 않고 필요한 문자열 하나만 확인합니다. 호스트 경로나 사내 레지스트리 정보도 공유 로그에서는 필요한 만큼 가립니다.

image='registry.example/team/api:Release_1'
printf 'image=<%s>\n' "$image"
# 실제 실행 전: image 값과 레지스트리·태그를 대조
: "${image:?image 변수가 비어 있습니다}"

마지막 줄은 변수가 없거나 비었을 때 중단시키는 셸 검사입니다. 비어 있지 않다고 Docker 문법까지 통과하는 검증기는 아닙니다. CI에서 변수를 다른 단계에 선언했는지, job 범위가 달라졌는지, 조합 과정에서 빈 태그나 공백이 들어갔는지 확인합니다. 실제 조직의 토큰을 출력하는 set -x 방식은 여기서 사용하지 않습니다.

4. 공백이 있는 옵션 값은 하나의 인수로 묶는다

볼륨 경로나 환경 값에 공백이 있다면 셸이 값을 몇 개의 인수로 나누는지 확인합니다. 예를 들어 Bash에서 -v "$PWD/data files:/data"는 경로 문자열을 하나로 묶는 방식입니다. 이는 형식 설명이며 마운트 경로의 존재·권한·Docker Desktop 공유 설정까지 검증한 것은 아닙니다. 운영 디렉터리를 시험 목적으로 바로 연결하지 마세요.

확인 방법과 주의사항

이미지 참조와 옵션 위치를 고친 뒤 승인된 시험 환경에서만 최소 명령으로 확인합니다. 오류가 pull access denied나 manifest unknown으로 바뀌었다면 이름을 해석한 뒤 접근 권한 또는 태그 존재를 확인하는 단계로 넘어갔을 수 있습니다. 새 오류를 원래 문법 오류와 구분하고, 권한을 넓히거나 인증 정보를 로그에 남겨 해결하지 않습니다.

로컬에 있어야 하는 이미지라면 먼저 docker image ls의 저장소·태그를 대조할 수 있습니다. 실제 컨테이너 실행은 이미지의 기본 명령을 수행하고 파일이나 네트워크에 영향을 줄 수 있으므로 문법 검사만 하려는 목적과 구분하세요. 이 글에서는 Docker 실행이나 컨테이너 생성 시험을 하지 않았습니다. 바꾼 배포 문자열은 원본을 보존하고 해당 항목만 되돌릴 수 있게 기록합니다.

FAQ

대문자를 모두 없애면 되나요? 저장소 경로와 태그 규칙이 다르므로 잘못된 부분만 수정합니다.

이미지를 다시 빌드해야 하나요? 인수 해석 단계의 문제라면 재빌드로 해결되지 않습니다.

CI에서만 실패하면? 셸 종류·변수 범위·공백과 인용 부호를 로컬과 비교합니다.

공식 출처와 관련 글

자료 확인일: 2026년 10월 17일. 공식 문서 기반 설명이며 실제 서비스·명령 실행 시험은 수행하지 않았습니다. 설치 버전과 리전·지원 범위는 적용 전에 확인하세요.

Docker run 명령 구조

Docker 이미지 이름 구성

Distribution 이미지 참조 문법

관련 글: Compose 환경 변수는 .env와 env_file의 적용 범위를 구분

적용 전 원본 설정을 보존하고 승인된 시험 범위에서 결과를 확인하세요.