So beheben Sie den Fehler „Docker: Ungültiges Referenzformat“

Docker vereinfacht das Erstellen, Ausführen und Verwalten von Containern. Beim Ausführen oder Erstellen eines Images kann jedoch der Fehler „Ungültiges Referenzformat“ auftreten. In den meisten Fällen liegt dies an einem geringfügigen Formatierungsfehler im Imagenamen oder -tag. Der Fehler kann beispielsweise auf Großbuchstaben, Sonderzeichen oder fehlende Werte zurückzuführen sein. Diese Anleitung erklärt die häufigsten Ursachen dieses Fehlers und zeigt, wie Sie ihn beheben können, um ein erneutes Auftreten zu verhindern.

Fehler „Ungültiges Referenzformat“ beheben

Lassen Sie uns die häufigsten Ursachen für den Fehler „Ungültiges Referenzformat“ und dessen Behebung herausfinden:

Großbuchstaben in Bildnamen

Docker erfordert, dass Image-Namen klein geschrieben werden. Schon ein einzelner Großbuchstabe kann zu Formatierungsfehlern führen. Beispielsweise führt die Ausführung des folgenden Befehls zu einem Fehler:

docker pull NGINX

Um diesen Fehler zu vermeiden, überprüfen Sie vor dem Ausführen des Befehls immer, ob Ihr Bildname in Kleinbuchstaben geschrieben ist.

docker pull nginx

Sonderzeichen oder ungültiges Zeichen

Manchmal fügen Benutzer versehentlich Zeichen hinzu, die Docker nicht zulässt. Dazu gehören @-Zeichen, Leerzeichen oder von einer Website oder einem Dokument kopierte Zeichen, die normal aussehen, es aber nicht sind.

Beispielsweise enthält der folgende Befehl das Sonderzeichen @, was den folgenden Fehler verursacht:

docker run ubuntu@:latest

Um diesen Fehler zu beheben, stellen Sie sicher, dass der Befehl keine zusätzlichen Zeichen oder Formatierungsfehler enthält. Sie können den Befehl mit einem Texteditor überprüfen und ggf. bereinigen:

docker run ubuntu:latest

Doppelpunkt ohne Tag

Einer der häufigsten Fehler besteht darin, am Ende des Bildnamens einen Doppelpunkt zu setzen, ohne das Tag einzuschließen. Versuchen wir beispielsweise den folgenden Befehl, um Node abzurufen:

docker pull node:

Docker erwartet nach dem Doppelpunkt einen Wert, z. B. latest , 18-alpine oder einen anderen gültigen Tag. Wenn kein Wert angegeben wird, gilt der Image-Name als unvollständig und führt zu einem Fehler „Ungültiges Referenzformat“:

Um diesen Fehler zu beheben, fügen Sie nach dem Doppelpunkt ein entsprechendes Tag hinzu, um den Bildnamen vollständig und gültig zu machen:

docker pull node:latest

Dateipfad oder Volume-Mount enthält Leerzeichen

Wenn Sie einen Dateipfad mit Leerzeichen angeben, insbesondere bei Optionen wie -v (Volume Mount), kann Docker Teile des Pfads fälschlicherweise als separate Argumente oder sogar als Teil des Image-Namens interpretieren. Dies kann zu unerwarteten Ergebnissen wie dem folgenden führen:

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

Um dies zu vermeiden, schließen Sie den Dateipfad immer mit Leerzeichen in doppelte Anführungszeichen ein, wie unten gezeigt:

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

Ersetzen Sie „/home/user/My Folder“ durch den tatsächlichen Pfad zum Verzeichnis, das Sie in den Container einbinden möchten.

Unangemessene Verwendung von Variablen

Bei der Arbeit mit Docker werden häufig Variablen in Befehlen verwendet, insbesondere bei der Angabe von Image-Versionen. Wenn eine Variable wie $VERSION jedoch nicht korrekt gesetzt ist, können in Docker Probleme wie der Fehler „Ungültiges Referenzformat“ auftreten.

Führen Sie beispielsweise den folgenden Befehl aus, um Ubuntu vom Docker Hub abzurufen:

docker pull ubuntu:$VERSION

Hier soll $VERSION die Version des Ubuntu-Images darstellen, das Sie abrufen möchten. Wenn Sie ihm jedoch keinen Wert zuweisen, interpretiert Docker den Befehl als „docker pull ubuntu:“. Dies führt zu einem ungültigen Image-Namen, da er mit einem Doppelpunkt endet und der erforderliche Versions-Tag fehlt.

Um dies zu vermeiden, stellen Sie sicher, dass alle im Befehl verwendeten Variablen richtig definiert sind. Unter Linux können Sie eine Variable mit der folgenden Syntax festlegen.

$VERSION=latest

Rufen Sie dann die angegebene Version ab, indem Sie den folgenden Befehl ausführen.

docker pull ubuntu:$VERSION

In Windows CMD müssen Sie das Schlüsselwort „set“ verwenden, um eine Variable (wie „Version“) zu definieren, und dann die Syntax „%VARIABLE%“ verwenden , um in Befehlen wie „Docker Pull“ darauf zu verweisen.

set VERSION=latest
docker pull ubuntu:%VERSION%

Hier enthält $VERSION den aktuellsten Wert, sodass Docker das ubuntu:latest- Image problemlos abrufen kann. Bei Bedarf können Sie auch eine bestimmte Version zuweisen, z. B. 18.04.

Problem beim Kopieren und Einfügen

Manchmal kopieren Benutzer Befehle aus Online-Tutorials oder Dokumentationen. Diese kopierten Befehle können versteckte Zeichen wie unsichtbare Leerzeichen, nicht-englische Satzzeichen oder spezielle Anführungszeichen enthalten. Diese Zeichen können Ihre Docker-Befehle unbemerkt beschädigen.

Um dies zu vermeiden, ist es besser, den Befehl nach Möglichkeit selbst einzugeben oder ihn zunächst in einen einfachen Texteditor einzufügen, um unerwünschte Formatierungen zu entfernen.

Da Sie nun die häufigsten Ursachen für den Fehler „Ungültiges Referenzformat“ in Docker kennen und wissen, wie Sie ihn beheben können, sind Sie auf dem besten Weg, dieses Problem in Zukunft zu vermeiden. Von der Überprüfung der Groß- und Kleinschreibung bis hin zur korrekten Variableneinstellung – diese einfachen Tipps können Ihnen viel Zeit und Ärger ersparen. Wenn Sie bereit sind, tiefer in die Materie einzusteigen, möchten Sie vielleicht auch lernen, wie Sie Ihre benutzerdefinierten Docker-Images taggen und in die Registry pushen oder wie Sie nicht verwendete Images bereinigen, um Ihr System sauber zu halten.