Risoluzione passo passo dell’errore “Docker: formato di riferimento non valido”

Docker semplifica il processo di sviluppo, esecuzione e gestione dei container. Tuttavia, un ostacolo comune che gli utenti incontrano è l’errore ” Formato di riferimento non valido ” che si verifica durante la creazione o l’esecuzione di un’immagine. In genere, questo errore deriva da piccoli problemi di formattazione nel nome o nel tag dell’immagine, che possono includere lettere maiuscole, caratteri speciali o un tag vuoto. In questo articolo, approfondiremo le cause più comuni di questo errore e offriremo soluzioni per evitarlo in futuro.

Comprensione dell’errore “Formato di riferimento non valido” in Docker

L’errore “Formato di riferimento non valido” indica che Docker non è in grado di interpretare il nome dell’immagine fornito a causa di una formattazione non corretta. Affinché Docker elabori correttamente le richieste, i nomi delle immagini devono rispettare una struttura specifica.

La sintassi richiesta è la seguente:

[registry/][repository][:tag]

Per garantire la conformità, attenersi alle seguenti linee guida:

Nei nomi delle immagini Docker utilizzare sempre lettere minuscole; le lettere maiuscole non sono consentite.
Utilizzare valori numerici, trattini (-), punti (.) e caratteri di sottolineatura (_) per separare le parole o indicare le versioni, ad esempio my-app_v1.0.
Evitate caratteri speciali come @, #, ! o $ perché non sono consentiti.
Rispettare le convenzioni di denominazione DNS: ogni segmento del nome dell’immagine (separato da barre o punti) deve avere una lunghezza compresa tra 1 e 63 caratteri e i trattini non devono essere posizionati all’inizio o alla fine.
Il nome completo dell’immagine, inclusi eventuali dettagli di registro e tag, non deve superare i 255 caratteri.

Risoluzione dell’errore “Formato di riferimento non valido”

Esaminiamo le cause più comuni dell’errore “formato di riferimento non valido” e come correggerle:

Problemi con le lettere maiuscole nei nomi delle immagini

Docker impone che tutti i nomi delle immagini siano interamente in minuscolo. La presenza di una sola lettera maiuscola può causare problemi di formattazione. Ad esempio, l’esecuzione del seguente comando genererà un errore:

docker pull NGINX

Il nome del repository deve essere in minuscolo

Per attenuare questo problema, assicurati sempre che i nomi delle immagini siano in minuscolo prima di eseguire il comando:

docker pull nginx

Esame dei caratteri speciali o non validi

Involontariamente, gli utenti potrebbero includere caratteri non consentiti nei loro comandi, inclusi spazi o il simbolo @.Ad esempio, il seguente comando include un carattere speciale che genererà un errore:

docker run ubuntu@:latest

Per risolvere questi errori, assicurati che non ci siano caratteri estranei nei tuoi comandi. Puoi scegliere di utilizzare un editor di testo normale per la verifica e la correzione:

docker run ubuntu:latest

Problemi con i due punti privi di tag

Un errore frequente consiste nell’inserire due punti alla fine del nome dell’immagine senza un tag. Ad esempio, quando si tenta di estrarre Node utilizzando il comando seguente:

docker pull node:

Docker prevede un tag post-due punti, come latesto 18-alpine. Se omesso, il comando restituisce un nome immagine incompleto, causando l’errore “formato di riferimento non valido”:

Per risolvere questo problema, aggiungi un tag valido dopo i due punti nel nome dell’immagine:

docker pull node:latest

Percorsi di file o montaggi di volumi contenenti spazi

L’inclusione di percorsi di file che presentano spazi, in particolare con opzioni come -vil montaggio di volumi, potrebbe causare un’interpretazione errata di segmenti del percorso da parte di Docker. Questo può portare a comportamenti imprevisti:

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

Per eliminare questo problema, incapsula tutti i percorsi con spazi tra virgolette doppie, come mostrato di seguito:

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

Assicurati di sostituire “/home/user/My Folder” con il percorso effettivo che intendi montare nel contenitore.

Uso improprio delle variabili

Se una variabile come “.exe” $VERSIONnon è configurata correttamente, può causare l’errore “formato di riferimento non valido” in Docker. Ad esempio, si consideri il comando seguente, che tenta di estrarre un’immagine dal Docker Hub:

docker pull ubuntu:$VERSION

In questo caso, se $VERSIONnon è impostato, Docker legge il comando come docker pull ubuntu:, generando un nome di immagine errato poiché termina con due punti senza un tag valido.

Per evitare questo problema, assicurati che tutte le variabili utilizzate nei comandi siano definite correttamente. In un ambiente Linux, imposta una variabile utilizzando la seguente sintassi:

$VERSION=latest

Successivamente, puoi estrarre la versione designata eseguendo:

docker pull ubuntu:$VERSION

In Windows CMD, utilizza la setsintassi per definire una variabile e farvi riferimento con il %VARIABLE%formato. Ad esempio:

set VERSION=latestdocker pull ubuntu:%VERSION%

Impostando $VERSIONl’ultima versione è possibile estrarre l’ ubuntu:latestimmagine senza errori.È anche possibile assegnare tag di versione specifici, come ad esempio 18.04, in base alle proprie esigenze.

Errori comuni di copia-incolla

Gli utenti spesso copiano comandi da fonti online, ma questi potrebbero includere inavvertitamente caratteri nascosti come spazi invisibili o segni di punteggiatura insoliti. Questi caratteri nascosti possono compromettere i comandi Docker.

Per evitare queste insidie, prova a digitare manualmente i comandi quando possibile, oppure incollali prima in un editor di testo normale per eliminare qualsiasi formattazione indesiderata.

Conclusione

Con la comprensione delle cause principali dell’errore “Formato di riferimento non valido” in Docker e delle soluzioni pratiche, ora sei pronto a prevenire questo problema. Controllare regolarmente la presenza di errori di capitalizzazione, garantire la corretta assegnazione delle variabili e prestare attenzione a caratteri speciali e spazi può semplificare notevolmente la tua esperienza con Docker.

Fonte e immagini