“Docker: 잘못된 참조 형식” 오류 단계별 해결

Docker는 컨테이너 개발, 실행 및 관리 프로세스를 간소화합니다.하지만 사용자가 흔히 겪는 문제 중 하나는 이미지 생성 또는 실행 중에 발생하는 ” 잘못된 참조 형식 ” 오류입니다.일반적으로 이 오류는 이미지 이름이나 태그의 사소한 형식 문제로 인해 발생하며, 여기에는 대문자, 특수 문자 또는 빈 태그가 포함될 수 있습니다.이 글에서는 이 오류의 일반적인 원인을 자세히 살펴보고 향후 이 오류를 방지하기 위한 해결책을 제시합니다.

Docker의 “잘못된 참조 형식” 오류 이해

“잘못된 참조 형식” 오류는 Docker가 잘못된 형식으로 인해 제공된 이미지 이름을 해석할 수 없음을 나타냅니다. Docker가 요청을 정확하게 처리하려면 이미지 이름이 특정 구조를 따라야 합니다.

필요한 구문은 다음과 같습니다.

[registry/][repository][:tag]

규정 준수를 위해 다음 지침을 준수하세요.

항상 소문자를 사용하세요. Docker 이미지 이름에는 대문자를 사용할 수 없습니다.
단어를 구분하거나 버전을 표시하려면 숫자 값, 하이픈(-), 마침표(.), 밑줄(_)을 활용합니다(예: my-app_v1.0.
@, #, !, $와 같은 특수 문자는 허용되지 않으므로 사용하지 마세요.
DNS 명명 규칙을 따르세요.이미지 이름의 각 세그먼트(슬래시나 마침표로 구분)는 1~63자여야 하며 하이픈은 시작이나 끝에 위치하면 안 됩니다.
등록 및 태그 세부 정보를 포함한 전체 이미지 이름은 255자를 넘을 수 없습니다.

“잘못된 참조 형식” 오류 해결

“잘못된 참조 형식” 오류의 일반적인 원인과 이를 수정하는 방법을 살펴보겠습니다.

이미지 이름의 대문자 문제

Docker에서는 모든 이미지 이름을 모두 소문자로 작성해야 합니다.대문자가 하나만 있어도 형식 문제가 발생할 수 있습니다.예를 들어, 다음 명령을 실행하면 오류가 발생합니다.

docker pull NGINX

이 문제를 완화하려면 명령을 실행하기 전에 항상 이미지 이름이 소문자인지 확인하세요.

docker pull nginx

특수 문자 또는 잘못된 문자 검사

의도치 않게 사용자는 명령어에 공백이나 @ 기호 등 허용되지 않는 문자를 포함할 수 있습니다.예를 들어, 다음 명령어에는 오류를 발생시키는 특수 문자가 포함되어 있습니다.

docker run ubuntu@:latest

이러한 오류를 해결하려면 명령어에 불필요한 문자가 없는지 확인하세요.일반 텍스트 편집기를 사용하여 확인 및 수정하는 것이 좋습니다.

docker run ubuntu:latest

태그가 없는 콜론 문제

자주 발생하는 실수는 이미지 이름 끝에 태그를 붙이지 않고 콜론을 붙이는 것입니다.예를 들어, 아래 명령어를 사용하여 Node.js를 가져오려고 할 때 다음과 같은 오류가 발생합니다.

docker pull node:

latestDocker는 또는 와 같은 태그가 콜론 뒤에 올 것으로 예상합니다 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”를 컨테이너에 마운트하려는 실제 경로로 바꿔야 합니다.

변수의 부적절한 사용

변수와 같은 것이 $VERSION제대로 구성되지 않으면 Docker에서 “잘못된 참조 형식” 오류가 발생할 수 있습니다.예를 들어, Docker Hub에서 이미지를 가져오려는 아래 명령을 살펴보겠습니다.

docker pull ubuntu:$VERSION

여기서 $VERSION가 설정되지 않으면 Docker는 명령을 로 읽습니다 docker pull ubuntu:.유효한 태그 없이 콜론으로 끝나므로 잘못된 이미지 이름이 생성됩니다.

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

$VERSION=latest

그 후, 다음을 실행하여 지정된 버전을 가져올 수 있습니다.

docker pull ubuntu:$VERSION

Windows CMD에서 set다음 구문을 사용하여 변수를 정의하고 해당 %VARIABLE%형식으로 참조합니다.예:

set VERSION=latestdocker pull ubuntu:%VERSION%

최신 버전으로 설정하면 오류 없이 $VERSION이미지를 원활하게 가져올 수 있습니다 ubuntu:latest.필요에 따라 18.04와 같은 특정 버전 태그를 지정할 수도 있습니다.

일반적인 복사-붙여넣기 오류

사용자는 종종 온라인 소스에서 명령어를 복사하지만, 이러한 명령어에는 보이지 않는 공백이나 특수한 구두점과 같은 숨겨진 문자가 의도치 않게 포함될 수 있습니다.이러한 숨겨진 문자는 Docker 명령어를 방해할 수 있습니다.

이러한 함정을 피하려면 가능한 한 명령을 직접 입력하거나 일반 텍스트 편집기에 붙여넣어 원치 않는 서식을 삭제하세요.

결론

Docker에서 “잘못된 참조 형식” 오류의 주요 원인과 실질적인 해결책을 이해했으므로 이제 이 문제가 더 이상 발생하지 않도록 예방할 준비가 되었습니다.대소문자 오류를 정기적으로 확인하고, 변수 할당이 올바른지 확인하고, 특수 문자와 공백을 주의하면 Docker 환경을 크게 간소화할 수 있습니다.

출처 및 이미지