Schrittweise Behebung des Fehlers „Docker: Ungültiges Referenzformat“

Docker vereinfacht die Entwicklung, Ausführung und Verwaltung von Containern. Ein häufiges Hindernis für Benutzer ist jedoch der Fehler „ Ungültiges Referenzformat “, der bei der Image-Erstellung oder -Ausführung auftritt. Typischerweise resultiert dieser Fehler aus kleineren Formatierungsfehlern im Image-Namen oder -Tag, die Großbuchstaben, Sonderzeichen oder ein leeres Tag enthalten können. In diesem Artikel gehen wir auf die häufigsten Ursachen dieses Fehlers ein und bieten Lösungen, um ihn in Zukunft zu vermeiden.

Den Fehler „Ungültiges Referenzformat“ in Docker verstehen

Der Fehler „Ungültiges Referenzformat“ bedeutet, dass Docker den von Ihnen angegebenen Image-Namen aufgrund einer falschen Formatierung nicht interpretieren kann. Damit Docker Anfragen korrekt verarbeiten kann, müssen Image-Namen einer bestimmten Struktur entsprechen.

Die erforderliche Syntax lautet wie folgt:

[registry/][repository][:tag]

Um die Einhaltung sicherzustellen, halten Sie sich an diese Richtlinien:

Verwenden Sie immer Kleinbuchstaben. Großbuchstaben sind in Docker-Image-Namen nicht zulässig.
Verwenden Sie numerische Werte, Bindestriche (-), Punkte (.) und Unterstriche (_), um Wörter zu trennen oder Versionen anzuzeigen, z. B.my-app_v1.0.
Vermeiden Sie Sonderzeichen wie @, #, ! oder $, da diese nicht zulässig sind.
Befolgen Sie die DNS-Benennungskonventionen: Jedes Segment des Bildnamens (durch Schrägstriche oder Punkte getrennt) muss zwischen 1 und 63 Zeichen lang sein, und am Anfang oder Ende dürfen keine Bindestriche stehen.
Der vollständige Bildname darf einschließlich aller Registrierungs- und Tag-Details nicht länger als 255 Zeichen sein.

Beheben des Fehlers „Ungültiges Referenzformat“

Lassen Sie uns die häufigsten Auslöser des Fehlers „ungültiges Referenzformat“ und deren Behebung untersuchen:

Probleme mit Großbuchstaben in Bildnamen

Docker schreibt vor, dass alle Image-Namen vollständig in Kleinbuchstaben geschrieben werden müssen. Bereits ein einzelner Großbuchstabe kann zu Formatierungsproblemen führen. Beispielsweise führt die Ausführung des folgenden Befehls zu einem Fehler:

docker pull NGINX

Der Repo-Name muss in Kleinbuchstaben geschrieben sein

Um dieses Problem zu beheben, stellen Sie vor der Ausführung des Befehls immer sicher, dass Ihre Bildnamen in Kleinbuchstaben geschrieben sind:

docker pull nginx

Prüfung auf Sonderzeichen oder ungültige Zeichen

Benutzer können unbeabsichtigt unzulässige Zeichen in ihre Befehle einbauen, darunter Leerzeichen oder das @-Symbol. Beispielsweise enthält der folgende Befehl ein Sonderzeichen, das einen Fehler auslöst:

docker run ubuntu@:latest

Um solche Fehler zu beheben, stellen Sie sicher, dass Ihre Befehle keine überflüssigen Zeichen enthalten. Sie können zur Überprüfung und Korrektur einen Texteditor verwenden:

docker run ubuntu:latest

Probleme mit Doppelpunkten ohne Tags

Ein häufiger Fehler besteht darin, einen Doppelpunkt am Ende des Bildnamens zu platzieren, ohne ein Tag hinzuzufügen. Beispielsweise beim Versuch, Node mit dem folgenden Befehl zu pullen:

docker pull node:

Docker erwartet nach dem Doppelpunkt ein Tag, z. B.latestoder 18-alpine. Wird dieses weggelassen, führt der Befehl zu einem unvollständigen Image-Namen und dem Fehler „ungültiges Referenzformat“:

Um dieses Problem zu beheben, fügen Sie nach dem Doppelpunkt in Ihrem Bildnamen ein gültiges Tag hinzu:

docker pull node:latest

Dateipfade oder Volume-Mounts mit Leerzeichen

Das Einfügen von Dateipfaden mit Leerzeichen, insbesondere bei Optionen wie -vVolume-Mounts, kann dazu führen, dass Docker Pfadsegmente falsch interpretiert. Dies kann zu unerwartetem Verhalten führen:

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

Um dieses Problem zu beheben, schließen Sie alle Pfade mit Leerzeichen in doppelte Anführungszeichen ein, wie unten gezeigt:

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

Stellen Sie sicher, dass Sie „/home/user/Mein Ordner“ durch den tatsächlichen Pfad ersetzen, den Sie in den Container einbinden möchten.

Unsachgemäße Verwendung von Variablen

Wenn eine Variable wie diese $VERSIONnicht richtig konfiguriert ist, kann dies in Docker zum Fehler „ungültiges Referenzformat“ führen. Betrachten Sie beispielsweise den folgenden Befehl, der versucht, ein Image vom Docker Hub abzurufen:

docker pull ubuntu:$VERSION

Wenn hier $VERSIONnicht festgelegt ist, liest Docker den Befehl als docker pull ubuntu:, was zu einem fehlerhaften Image-Namen führt, da er mit einem Doppelpunkt ohne gültiges Tag endet.

Um dies zu verhindern, stellen Sie sicher, dass alle in Ihren Befehlen verwendeten Variablen korrekt definiert sind. In einer Linux-Umgebung legen Sie eine Variable mit der folgenden Syntax fest:

$VERSION=latest

Anschließend können Sie die angegebene Version abrufen, indem Sie Folgendes ausführen:

docker pull ubuntu:$VERSION

Verwenden Sie in Windows CMD die setSyntax, um eine Variable zu definieren und mit dem %VARIABLE%Format darauf zu verweisen. Beispiel:

set VERSION=latestdocker pull ubuntu:%VERSION%

Die Einstellung „Neueste“ ermöglicht ein reibungsloses und fehlerfreies $VERSIONAbrufen des Images. Bei Bedarf können auch spezifische Versions-Tags, z. B.18.04, zugewiesen werden.ubuntu:latest

Häufige Fehler beim Kopieren und Einfügen

Benutzer kopieren häufig Befehle aus Online-Quellen. Diese können jedoch versehentlich versteckte Zeichen wie unsichtbare Leerzeichen oder ungewöhnliche Satzzeichen enthalten. Solche versteckten Zeichen können Ihre Docker-Befehle stören.

Um diese Fallstricke zu vermeiden, versuchen Sie, Befehle, wenn möglich, manuell einzugeben oder sie zunächst in einen einfachen Texteditor einzufügen, um unerwünschte Formatierungen zu entfernen.

Abschluss

Mit dem Verständnis der Hauptursachen für den Fehler „Ungültiges Referenzformat“ in Docker und praktischen Lösungen sind Sie nun in der Lage, dieses Problem zukünftig zu vermeiden. Regelmäßige Überprüfung auf Groß- und Kleinschreibung, korrekte Variablenzuweisungen und der Umgang mit Sonderzeichen und Leerzeichen können Ihre Docker-Erfahrung deutlich verbessern.

Quelle & Bilder