Build

invalid reference format – Docker INVALID_REFERENCE_FORMAT

INVALID_REFERENCE_FORMAT

L'errore Docker invalid reference format indica che il riferimento a un'immagine non rispetta la sintassi prevista per registry, repository o tag. Può dipendere da maiuscole, spazi, un separatore errato, una variabile vuota o un tag costruito male nello script di build. Il controllo iniziale consiste nel stampare il valore finale passato a Docker e confrontarlo con il formato host/namespace/repository:tag.

Categoria: DockerGruppo: BuildConfidenza: altaUltimo aggiornamento: 19-08-2026Letto 18 volte

Cosa significa questo errore?

L'errore Docker invalid reference format indica che il riferimento a un'immagine non rispetta la sintassi prevista per registry, repository o tag. Può dipendere da maiuscole, spazi, un separatore errato, una variabile vuota o un tag costruito male nello script di build. Il controllo iniziale consiste nel stampare il valore finale passato a Docker e confrontarlo con il formato host/namespace/repository:tag.

Messaggio originale

invalid reference format

Contesto e parole chiave

Alias

  • Error parsing reference
  • not a valid repository/tag

Messaggi alternativi

  • Formato immagine Docker non valido
  • Nome repository o tag non conforme

Prodotti

  • Docker Engine / Docker CLI

Piattaforme

  • Linux
  • macOS
  • Windows

Parole chiave

  • docker image tag errore
  • docker invalid reference format
  • docker repository tag non valido

Cause possibili

Repository o tag con caratteri non ammessi

Il nome contiene maiuscole, spazi o caratteri che non appartengono alla grammatica dei riferimenti Docker.

molto comune

Variabile di pipeline vuota o concatenata male

Uno script produce un riferimento incompleto come :latest o inserisce un separatore in posizione errata.

comune

Diagnosi

Riferimento finale dell'immagine

Stampare la variabile o il comando completo prima di docker build, tag o push.

Come leggere il risultato. Il valore deve contenere un repository valido e, se presente, un tag dopo un solo separatore colon.

bash
printf 'IMAGE_REF=<%s>\n' $IMAGE_REF

Caratteri e segmenti del nome

Provare il riferimento con docker image tag o con una stringa minima nota.

Come leggere il risultato. Se il riferimento minimo funziona, l'errore è nella costruzione del nome usato dalla pipeline.

bash
docker image tag alpine:latest registry.example/team/app:1.0

Risoluzione

Normalizzazione del nome immagine

Difficoltà: facileRischio: basso

Generare repository e tag in minuscolo, senza spazi e con separatori validi.

  1. Separare registry, repository e tag.
  2. Convertire in minuscolo i segmenti ammessi.
  3. Rimuovere spazi e caratteri non validi.
  4. Rifiutare la pipeline se una variabile obbligatoria è vuota.

Correzione della sintassi di tag e registry

Difficoltà: mediaRischio: basso

Usare il formato documentato e non confondere porta del registry con separatore del tag.

  1. Applicare il formato host:porta/namespace/repository:tag quando necessario.
  2. Verificare che il repository sia presente nel registry.
  3. Eseguire il tag localmente.
  4. Ripetere build e push dopo la verifica.

Domande frequenti

Il carattere più spesso responsabile dell'errore è lo spazio?

Gli spazi sono una causa frequente, ma anche maiuscole, variabili vuote e separatori errati possono rendere invalido il riferimento finale.

Approfondimenti

Schede correlate