Como corrigir o erro “Docker: Formato de referência inválido”

O Docker facilita a criação, a execução e o gerenciamento de contêineres. No entanto, você pode encontrar o erro "Formato de Referência Inválido" ao executar ou criar uma imagem. Na maioria dos casos, isso se deve a um pequeno erro de formatação no nome ou na tag da imagem. Por exemplo, o erro pode ser devido a letras maiúsculas, caracteres especiais ou valores ausentes. Este guia explicará as causas comuns desse erro e como corrigi-lo para evitar que ele aconteça novamente.

Corrigir erro "Formato de referência inválido"

Vamos descobrir as causas mais comuns do erro "Formato de referência inválido" e como corrigi-lo:

Letras maiúsculas em nomes de imagens

O Docker exige que os nomes das imagens sejam escritos em letras minúsculas. Mesmo uma única letra maiúscula pode causar erros de formatação. Por exemplo, executar o seguinte comando resultará em um erro:

docker pull NGINX

Para evitar esse erro, sempre verifique se o nome da imagem está em letras minúsculas antes de executar o comando.

docker pull nginx

Caractere especial ou inválido

Às vezes, os usuários adicionam acidentalmente caracteres que o Docker não permite. Isso inclui símbolos @, espaços ou caracteres copiados de um site ou documento que parecem normais, mas não são.

Por exemplo, o comando a seguir contém o caractere especial @, o que causará o seguinte erro:

docker run ubuntu@:latest

Para corrigir esse erro, certifique-se de que não haja caracteres extras ou problemas de formatação no comando. Você pode usar um editor de texto simples para verificar e limpar o comando (se necessário):

docker run ubuntu:latest

Dois pontos sem etiqueta

Um dos erros mais comuns é colocar dois pontos no final do nome da imagem, mas não incluir a tag. Por exemplo, vamos tentar o seguinte comando para extrair o Node:

docker pull node:

O Docker espera um valor após os dois pontos, como latest, 18-alpine ou qualquer outra tag válida. Se nenhum valor for fornecido, o nome da imagem será considerado incompleto e causará o erro "Formato de Referência Inválido":

Para corrigir esse erro, adicione uma tag apropriada após os dois pontos para tornar o nome da imagem completo e válido:

docker pull node:latest

O caminho do arquivo ou a montagem do volume contém espaços

Ao incluir um caminho de arquivo que contém espaços, especialmente com opções como -v (montagem de volume), o Docker pode interpretar incorretamente partes do caminho como argumentos separados ou até mesmo como parte do nome da imagem. Como resultado, você pode encontrar resultados inesperados como o mostrado abaixo:

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

Para evitar isso, sempre coloque o caminho do arquivo entre espaços e aspas duplas, conforme mostrado abaixo:

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

Substitua “/home/user/Minha Pasta” pelo caminho real para o diretório que você deseja montar no contêiner.

Uso inadequado de variáveis

Ao trabalhar com o Docker, é comum usar variáveis ​​em comandos, especialmente ao especificar versões de imagens. No entanto, se uma variável como $VERSION não for definida corretamente, o Docker poderá encontrar problemas como o erro "Formato de Referência Inválido".

Por exemplo, execute o seguinte comando para extrair o Ubuntu do Docker Hub:

docker pull ubuntu:$VERSION

Aqui, $VERSION deve representar a versão da imagem do Ubuntu que você deseja extrair. Mas se você não atribuir um valor a ela, o Docker interpretará o comando como "docker pull ubuntu:". Isso resulta em um nome de imagem inválido, pois termina com dois pontos e não possui a tag de versão necessária.

Para evitar isso, certifique-se de que todas as variáveis ​​usadas no comando estejam definidas corretamente. No Linux, você pode definir uma variável usando a seguinte sintaxe.

$VERSION=latest

Em seguida, extraia a versão especificada executando o seguinte comando.

docker pull ubuntu:$VERSION

No Windows CMD, você precisa usar a palavra-chave set para definir uma variável (como version) e, em seguida, usar a sintaxe %VARIABLE% para se referir a ela em comandos como docker pull.

set VERSION=latest
docker pull ubuntu:%VERSION%

Aqui, $VERSION contém o valor mais recente, então o Docker extrai a imagem ubuntu:latest sem problemas. Você também pode atribuir uma versão específica, como 18.04, se necessário.

Problema de copiar e colar

Às vezes, os usuários copiam comandos de tutoriais ou documentação online. Esses comandos copiados podem conter caracteres ocultos, como espaços invisíveis, pontuação não inglesa ou aspas especiais. Esses caracteres podem corromper silenciosamente seus comandos do Docker.

Para evitar isso, é melhor digitar o comando você mesmo, quando possível, ou colá-lo em um editor de texto simples primeiro para remover a formatação indesejada.

Agora que você conhece as causas comuns do erro "Formato de Referência Inválido" no Docker e como corrigi-lo, estará no caminho certo para evitar esse problema no futuro. Da verificação de capitalização à garantia de que suas variáveis ​​estejam definidas corretamente, essas dicas simples podem economizar muito tempo e frustração. Se estiver pronto para explorar mais a fundo, talvez você também queira aprender como marcar e enviar suas imagens personalizadas do Docker para o registro ou como limpar imagens não utilizadas para manter seu sistema limpo.