Resolvendo o erro “Docker: Formato de referência inválido” passo a passo

O Docker simplifica o processo de desenvolvimento, execução e gerenciamento de contêineres. No entanto, um obstáculo comum que os usuários enfrentam é o erro ” Formato de Referência Inválido “, que surge durante a criação ou execução de imagens. Normalmente, esse erro resulta de pequenos problemas de formatação no nome ou na tag da imagem, que podem incluir letras maiúsculas, caracteres especiais ou uma tag vazia. Neste artigo, abordaremos as principais causas desse erro e ofereceremos soluções para evitá-lo no futuro.

Compreendendo o erro “Formato de referência inválido” no Docker

O erro “Formato de Referência Inválido” significa que o Docker não consegue interpretar o nome da imagem fornecido devido à formatação incorreta. Para que o Docker processe as solicitações com precisão, os nomes das imagens devem obedecer a uma estrutura específica.

A sintaxe necessária é a seguinte:

[registry/][repository][:tag]

Para garantir a conformidade, siga estas diretrizes:

Use sempre letras minúsculas; letras maiúsculas não são permitidas em nomes de imagens do Docker.
Utilize valores numéricos, hifens (-), pontos (.) e sublinhados (_) para separar palavras ou indicar versões, como my-app_v1.0.
Evite caracteres especiais como @, #, ! ou $, pois eles não são permitidos.
Siga as convenções de nomenclatura de DNS: cada segmento do nome da imagem (separado por barras ou pontos) deve ter de 1 a 63 caracteres, e hifens não devem ser posicionados no início ou no fim.
O nome completo da imagem, incluindo quaisquer detalhes de registro e tag, não deve exceder 255 caracteres.

Resolvendo o erro “Formato de referência inválido”

Vamos examinar os gatilhos comuns do erro “formato de referência inválido” e como corrigi-los:

Problemas com letras maiúsculas em nomes de imagens

O Docker exige que todos os nomes de imagens sejam escritos inteiramente em letras minúsculas. A presença de uma única letra maiúscula pode causar problemas de formatação. Por exemplo, executar o seguinte comando gerará um erro:

docker pull NGINX

O nome do repositório deve estar em letras minúsculas

Para atenuar esse problema, sempre certifique-se de que os nomes das imagens estejam em letras minúsculas antes de executar o comando:

docker pull nginx

Exame de caracteres especiais ou inválidos

Involuntariamente, usuários podem incorporar caracteres não permitidos em seus comandos, incluindo espaços ou o símbolo @.Por exemplo, o comando a seguir inclui um caractere especial que acionará um erro:

docker run ubuntu@:latest

Para resolver esses erros, certifique-se de que não haja caracteres estranhos em seus comandos. Você pode optar por usar um editor de texto simples para verificação e correção:

docker run ubuntu:latest

Problemas com dois pontos sem tags

Um erro frequente é colocar dois pontos no final do nome da imagem sem uma tag. Por exemplo, ao tentar extrair o Node usando o comando abaixo:

docker pull node:

O Docker antecipa uma tag pós-dois-pontos, como latestor 18-alpine. Se omitido, o comando resultará em um nome de imagem incompleto, causando o erro “formato de referência inválido”:

Para resolver isso, adicione uma tag válida após os dois pontos no nome da sua imagem:

docker pull node:latest

Caminhos de arquivo ou montagens de volume contendo espaços

Incluir caminhos de arquivo com espaços, principalmente com opções como -vmontagens de volume, pode fazer com que o Docker interprete incorretamente segmentos do caminho. Isso pode levar a comportamentos inesperados:

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

Para eliminar esse problema, encapsule todos os caminhos com espaços entre aspas duplas, conforme mostrado abaixo:

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

Certifique-se de substituir “/home/user/Minha Pasta” pelo caminho real que você pretende montar no contêiner.

Uso impróprio de variáveis

Se uma variável como essa $VERSIONnão for configurada corretamente, isso pode levar ao erro “formato de referência inválido” no Docker. Por exemplo, considere o comando abaixo, que tenta extrair uma imagem do Docker Hub:

docker pull ubuntu:$VERSION

Aqui, se $VERSIONnão for definido, o Docker lê o comando como docker pull ubuntu:, resultando em um nome de imagem incorreto, pois termina com dois pontos sem uma tag válida.

Para evitar isso, certifique-se de que todas as variáveis utilizadas nos seus comandos estejam definidas corretamente. Em um ambiente Linux, defina uma variável usando a seguinte sintaxe:

$VERSION=latest

Depois, você pode obter a versão designada executando:

docker pull ubuntu:$VERSION

No Windows CMD, utilize a setsintaxe para definir uma variável e referenciá-la com o %VARIABLE%formato. Por exemplo:

set VERSION=latestdocker pull ubuntu:%VERSION%

Definir $VERSIONcomo mais recente permite extrair a ubuntu:latestimagem sem problemas e sem erros. Tags de versão específicas, como 18.04, também podem ser atribuídas conforme necessário.

Erros comuns de copiar e colar

Os usuários costumam copiar comandos de fontes online, mas estes podem inadvertidamente incluir caracteres ocultos, como espaços invisíveis ou sinais de pontuação incomuns. Esses caracteres ocultos podem atrapalhar seus comandos do Docker.

Para evitar essas armadilhas, tente digitar os comandos manualmente sempre que possível ou colá-los em um editor de texto simples primeiro para remover qualquer formatação indesejada.

Conclusão

Compreendendo as principais causas do erro “Formato de Referência Inválido” no Docker e soluções práticas, você agora está preparado para evitar que esse problema continue. Verificar regularmente se há erros de capitalização, garantir atribuições corretas de variáveis e ter cuidado com caracteres especiais e espaços pode otimizar significativamente sua experiência com o Docker.

Fonte e Imagens