Docker: 잘못된 참조 형식 오류를 수정하는 방법

Docker를 사용하면 컨테이너를 쉽게 빌드, 실행 및 관리할 수 있습니다. 하지만 이미지를 실행하거나 빌드할 때 "잘못된 참조 형식" 오류가 발생할 수 있습니다. 대부분의 경우 이미지 이름이나 태그의 사소한 형식 오류로 인해 발생합니다. 예를 들어 대문자, 특수 문자 또는 누락된 값이 원인일 수 있습니다. 이 가이드에서는 이 오류의 일반적인 원인과 재발 방지를 위한 해결 방법을 설명합니다.

"잘못된 참조 형식" 오류 수정

"잘못된 참조 형식" 오류의 가장 일반적인 원인과 해결 방법을 알아보겠습니다.

이미지 이름의 대문자

Docker에서는 이미지 이름을 소문자로 사용해야 합니다. 대문자가 하나라도 입력되면 형식 오류가 발생할 수 있습니다. 예를 들어, 다음 명령을 실행하면 오류가 발생합니다.

docker pull NGINX

이 오류를 방지하려면 명령을 실행하기 전에 이미지 이름이 소문자인지 항상 두 번 확인하세요.

docker pull nginx

특수 문자 또는 잘못된 문자

사용자가 Docker에서 허용하지 않는 문자를 실수로 추가하는 경우가 있습니다. 여기에는 @ 기호, 공백, 웹사이트나 문서에서 복사한 문자 등이 포함되는데, 겉보기에는 정상이지만 실제로는 정상이 아닙니다.

예를 들어, 다음 명령에는 특수 문자 @가 포함되어 있어 다음과 같은 오류가 발생합니다.

docker run ubuntu@:latest

이 오류를 해결하려면 명령에 불필요한 문자나 서식 문제가 없는지 확인하세요. 필요한 경우 일반 텍스트 편집기를 사용하여 명령을 확인하고 정리할 수 있습니다.

docker run ubuntu:latest

태그 없는 콜론

가장 흔한 실수 중 하나는 이미지 이름 끝에 콜론을 넣고 태그를 포함하지 않는 것입니다. 예를 들어, 다음 명령을 사용하여 Node.js를 가져오는 방법을 살펴보겠습니다.

docker pull node:

Docker는 콜론 뒤에 latest , 18-alpine 또는 기타 유효한 태그와 같은 값을 기대합니다. 값을 제공하지 않으면 이미지 이름이 불완전한 것으로 간주되어 "잘못된 참조 형식" 오류가 발생합니다.

이 오류를 해결하려면 콜론 뒤에 적절한 태그를 추가하여 이미지 이름을 완전하고 유효하게 만드세요.

docker pull node:latest

파일 경로 또는 볼륨 마운트에 공백이 포함되어 있습니다.

공백이 포함된 파일 경로를 포함할 때, 특히 -v(볼륨 마운트)와 같은 옵션을 사용할 경우, Docker가 경로의 일부를 별도의 인수 또는 이미지 이름의 일부로 잘못 해석할 수 있습니다. 결과적으로 아래와 같은 예상치 못한 결과가 발생할 수 있습니다.

docker run -v /home/user/My Folder:/app ubuntu

이를 방지하려면 아래와 같이 파일 경로를 항상 공백과 큰따옴표로 묶어야 합니다.

docker run -v "/home/user/My Folder:/app" ubuntu

"/home/user/My Folder"를 컨테이너에 마운트하려는 디렉토리의 실제 경로로 바꾸세요 .

변수의 부적절한 사용

Docker를 사용할 때, 특히 이미지 버전을 지정할 때 명령에 변수를 사용하는 것이 일반적입니다. 하지만 $VERSION과 같은 변수가 올바르게 설정되지 않으면 Docker에서 "잘못된 참조 형식" 오류와 같은 문제가 발생할 수 있습니다.

예를 들어, Docker Hub에서 Ubuntu를 가져오려면 다음 명령을 실행하세요.

docker pull ubuntu:$VERSION

여기서 $VERSION은 가져오려는 Ubuntu 이미지의 버전을 나타냅니다. 하지만 값을 지정하지 않으면 Docker는 명령을 "docker pull ubuntu:"로 해석합니다. 따라서 이미지 이름이 콜론으로 끝나고 필수 버전 태그가 없으므로 잘못된 이미지 이름이 생성됩니다.

이를 방지하려면 명령에 사용된 모든 변수가 올바르게 정의되어 있는지 확인하세요. Linux에서는 다음 구문을 사용하여 변수를 설정할 수 있습니다.

$VERSION=latest

그런 다음 다음 명령을 실행하여 지정된 버전을 가져옵니다.

docker pull ubuntu:$VERSION

Windows CMD에서는 set 키워드를 사용하여 변수(예: version)를 정의한 다음, %VARIABLE% 구문을 사용하여 docker pull과 같은 명령에서 해당 변수를 참조해야 합니다.

set VERSION=latest
docker pull ubuntu:%VERSION%

여기서 $VERSION은 최신 값을 저장하므로 Docker는 문제없이 ubuntu:latest 이미지를 가져옵니다 . 필요한 경우 18.04와 같은 특정 버전을 지정할 수도 있습니다.

복사 및 붙여넣기 문제

사용자가 온라인 튜토리얼이나 문서에서 명령어를 복사하는 경우가 있습니다. 이렇게 복사된 명령어에는 보이지 않는 공백, 영어가 아닌 구두점, 특수 따옴표 등 숨겨진 문자가 포함될 수 있습니다. 이러한 문자는 Docker 명령어를 의도치 않게 손상시킬 수 있습니다.

이를 방지하려면 가능하다면 명령을 직접 입력하거나 일반 텍스트 편집기에 명령을 붙여넣어 원치 않는 서식을 제거하는 것이 좋습니다.

이제 Docker에서 "잘못된 참조 형식" 오류의 일반적인 원인과 해결 방법을 알았으니 앞으로 이 문제를 방지하는 데 큰 도움이 될 것입니다. 대소문자 확인부터 변수 설정까지, 이 간단한 팁들을 활용하면 많은 시간과 번거로움을 줄일 수 있습니다. 더 자세히 알아보고 싶다면, 사용자 지정 Docker 이미지에 태그를 지정하고 레지스트리에 푸시하는 방법이나 사용하지 않는 이미지를 정리하여 시스템을 깔끔하게 유지하는 방법도 알아보세요.