Jak naprawić błąd „Docker: nieprawidłowy format odniesienia”

Docker ułatwia budowanie, uruchamianie i zarządzanie kontenerami. Jednak podczas uruchamiania lub budowania obrazu może wystąpić błąd „Nieprawidłowy format odniesienia”. W większości przypadków przyczyną jest drobny błąd formatowania nazwy lub tagu obrazu. Na przykład błąd może wynikać z użycia wielkich liter, znaków specjalnych lub brakujących wartości. Ten przewodnik wyjaśni najczęstsze przyczyny tego błędu i sposoby jego rozwiązania, aby zapobiec jego ponownemu wystąpieniu.

Napraw błąd „Nieprawidłowy format odniesienia”

Poznajmy najczęstsze przyczyny błędu „Nieprawidłowy format odniesienia” i dowiedzmy się, jak go naprawić:

Wielkie litery w nazwach obrazów

Docker wymaga, aby nazwy obrazów były pisane małymi literami. Nawet jedna wielka litera może spowodować błędy formatowania. Na przykład uruchomienie poniższego polecenia spowoduje błąd:

docker pull NGINX

Aby uniknąć tego błędu, zawsze przed uruchomieniem polecenia sprawdź, czy nazwa obrazu jest zapisana małymi literami.

docker pull nginx

Znak specjalny lub nieprawidłowy

Czasami użytkownicy przypadkowo dodają znaki niedozwolone przez Dockera. Należą do nich znaki @, spacje lub znaki skopiowane ze strony internetowej lub dokumentu, które wyglądają normalnie, ale takie nie są.

Na przykład poniższe polecenie zawiera znak specjalny @, który spowoduje następujący błąd:

docker run ubuntu@:latest

Aby naprawić ten błąd, upewnij się, że w poleceniu nie ma zbędnych znaków ani błędów formatowania. Możesz użyć edytora tekstu, aby sprawdzić i poprawić polecenie (w razie potrzeby):

docker run ubuntu:latest

Dwukropek bez znacznika

Jednym z najczęstszych błędów jest dodanie dwukropka na końcu nazwy obrazu bez dodania tagu. Na przykład, spróbujmy następującego polecenia, aby pobrać Node:

docker pull node:

Docker oczekuje wartości po dwukropku, takiej jak latest, 18-alpine lub dowolnego innego prawidłowego znacznika. W przypadku braku wartości nazwa obrazu zostanie uznana za niekompletną i spowoduje błąd „Nieprawidłowy format odniesienia”:

Aby naprawić ten błąd, dodaj odpowiedni tag po dwukropku, aby nazwa obrazu była pełna i prawidłowa:

docker pull node:latest

Ścieżka pliku lub miejsce zamontowania woluminu zawiera spacje

Jeśli ścieżka do pliku zawiera spacje, zwłaszcza z opcjami takimi jak -v (montowanie woluminu), Docker może błędnie zinterpretować części ścieżki jako osobne argumenty lub nawet jako część nazwy obrazu. W rezultacie mogą wystąpić nieoczekiwane rezultaty, takie jak te pokazane poniżej:

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

Aby tego uniknąć, zawsze umieszczaj ścieżkę dostępu do pliku w cudzysłowie, używając spacji, jak pokazano poniżej:

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

Zastąp „/home/user/My Folder” rzeczywistą ścieżką do katalogu, który chcesz zamontować w kontenerze.

Niewłaściwe użycie zmiennych

Podczas pracy z Dockerem często używa się zmiennych w poleceniach, zwłaszcza przy określaniu wersji obrazu. Jeśli jednak zmienna, taka jak $VERSION, nie jest poprawnie ustawiona, Docker może napotkać problemy, takie jak błąd „Nieprawidłowy format odniesienia”.

Na przykład uruchom następujące polecenie, aby pobrać Ubuntu z Docker Hub:

docker pull ubuntu:$VERSION

W tym przypadku zmienna $VERSION powinna reprezentować wersję obrazu Ubuntu, którą chcesz pobrać. Jeśli jednak nie przypiszesz jej wartości, Docker zinterpretuje polecenie jako „docker pull ubuntu:”. W rezultacie nazwa obrazu będzie nieprawidłowa, ponieważ kończy się dwukropkiem i nie zawiera wymaganego znacznika wersji.

Aby tego uniknąć, upewnij się, że wszystkie zmienne użyte w poleceniu są poprawnie zdefiniowane. W systemie Linux możesz ustawić zmienną, używając następującej składni.

$VERSION=latest

Następnie pobierz określoną wersję, wykonując następujące polecenie.

docker pull ubuntu:$VERSION

W wierszu poleceń CMD systemu Windows należy użyć słowa kluczowego set, aby zdefiniować zmienną (np. version), a następnie użyć składni %VARIABLE%, aby odwołać się do niej w poleceniach, takich jak docker pull.

set VERSION=latest
docker pull ubuntu:%VERSION%

W tym przypadku $VERSION przechowuje najnowszą wartość, więc Docker bez problemu pobiera obraz ubuntu:latest . W razie potrzeby można również przypisać konkretną wersję, na przykład 18.04.

Problem z kopiowaniem i wklejaniem

Czasami użytkownicy kopiują polecenia z samouczków online lub dokumentacji. Te skopiowane polecenia mogą zawierać ukryte znaki, takie jak niewidoczne spacje, znaki interpunkcyjne inne niż angielskie lub cudzysłowy. Znaki te mogą dyskretnie uszkodzić polecenia Dockera.

Aby tego uniknąć, lepiej jest wpisać polecenie ręcznie, o ile to możliwe, lub najpierw wkleić je do edytora zwykłego tekstu, aby usunąć niepożądane formatowanie.

Teraz, gdy znasz już najczęstsze przyczyny błędu „Nieprawidłowy format referencji” w Dockerze i wiesz, jak go naprawić, będziesz na dobrej drodze do uniknięcia tego problemu w przyszłości. Od sprawdzania kapitalizacji po upewnienie się, że zmienne są poprawnie ustawione – te proste wskazówki mogą zaoszczędzić Ci mnóstwo czasu i nerwów. Jeśli chcesz dowiedzieć się więcej, możesz również dowiedzieć się, jak tagować i przesyłać niestandardowe obrazy Dockera do rejestru, a także jak czyścić nieużywane obrazy, aby utrzymać system w czystości.