Imagem Base64 não aparece? 10 causas comuns e como resolver

Você codificou uma imagem em Base64, colou o data URI no HTML e… nada. Um ícone de imagem quebrada te encarando. Ou pior — funciona no Chrome mas quebra no Safari, funciona local mas falha em produção.

Erros de imagem Base64 são frustrantes porque a string parece correta à primeira vista. A causa real geralmente está escondida em um detalhe sutil: um caractere faltando no prefixo, espaços invisíveis introduzidos ao copiar e colar, ou um backend que silenciosamente fez double encoding dos seus dados. Este guia cobre todas as 10 causas mais comuns com exemplos de código e soluções.

Referência rápida: Sintoma → Causa → Solução

Comece por aqui. Encontre seu sintoma, confira a causa provável e pule direto para a solução detalhada abaixo.

Erros de prefixo: o data: URI está malformado

O esquema data URI tem uma sintaxe rígida. Um único caractere errado e o navegador trata sua string Base64 como uma URL quebrada em vez de dados de imagem.

Causa 1: Prefixo data URI completamente ausente

Se você atribui a string Base64 bruta diretamente ao src sem o prefixo data:image/...;base64,, o navegador interpreta como um caminho de URL relativo — resultado: um 404.

❌ <img src="iVBORw0KGgo..." />
✅ <img src="data:image/png;base64,iVBORw0KGgo..." />

Causa 2: Ponto e vírgula escrito como vírgula

Escrever data:image/png,base64,... em vez de data:image/png;base64,... faz o navegador tratar base64,... como texto puro em vez de um indicador de encoding Base64.

❌ data:image/png,base64,iVBORw0KGgo...
✅ data:image/png;base64,iVBORw0KGgo...

Causa 3: Vírgula faltando após "base64"

A vírgula entre base64 e os dados é obrigatória. Sem ela — data:image/png;base64iVBOR... — o navegador lê base64iVBOR... como um nome de charset, não como dados codificados.

❌ data:image/png;base64iVBORw0KGgo...
✅ data:image/png;base64,iVBORw0KGgo...

Corrupção de encoding: a string Base64 em si está quebrada

Mesmo com o prefixo correto, o conteúdo codificado pode ser silenciosamente corrompido durante o armazenamento, a transmissão ou um copiar e colar.

Causa 4: String truncada

Colunas de banco de dados com limite de caracteres (ex.: VARCHAR(65535)) truncam silenciosamente strings Base64. Um PNG de 100KB gera ~136.000 caracteres Base64. Se a coluna corta em 65.535, você obtém uma imagem semi-decodificada e corrompida. Solução: Usar colunas do tipo TEXT ou LONGTEXT para armazenar Base64.

Causa 5: Caracteres inválidos (espaços, caracteres especiais)

Base64 válido usa apenas A-Z, a-z, 0-9, +, / e =. Espaços introduzidos ao copiar e colar fazem atob() lançar InvalidCharacterError. Solução: Remover todos os espaços antes de usar: str.replace(/\s/g, '').

Causa 6: Poluição por quebras de linha

Ferramentas como openssl base64 inserem um \n a cada 76 caracteres por padrão (RFC 2045). Essas quebras de linha corrompem data URIs no HTML. Solução: Usar openssl base64 -A (saída em linha única) ou remover as quebras: str.replace(/[\r\n]/g, '').

Causa 7: Padding removido pelo parsing de URL

Os caracteres de padding (=) são frequentemente removidos quando a string passa por parâmetros de URL, já que = é um caractere reservado em URLs. Alguns navegadores toleram a ausência de padding, outros não — causando comportamento inconsistente entre ambientes. Solução: Fazer URL-encode da string Base64 antes de colocá-la em um parâmetro, ou re-paddar no lado receptor.

MIME incorreto: isso realmente quebra a imagem?

Isso surpreende a maioria dos desenvolvedores: declarar o tipo MIME errado geralmente não quebra a exibição da imagem.

Causa 8: MIME declarado não corresponde ao tipo real do arquivo

Se você escreve data:image/png;base64,/9j/4AAQ... (dados JPEG com MIME de PNG), a maioria dos navegadores modernos ainda renderiza corretamente graças ao content sniffing. Porém, pode falhar em dois cenários: (1) Content Security Policy (CSP) rígida com verificação de MIME, e (2) processamento server-side que confia no MIME declarado para conversão de formato. Veredicto: Corrija por precaução, mas raramente é a causa real da falha de exibição.

Erros de pipeline: dados corrompidos antes de chegar ao navegador

Estes são os casos mais difíceis de diagnosticar porque a string Base64 parece correta no seu código — a corrupção acontece durante a serialização ou a transmissão.

Causa 9: Double encoding Base64

Um backend que codifica dados já codificados produz o Base64 de uma string Base64. O resultado é ~33% mais longo que o esperado e, ao decodificar uma vez, você obtém texto em vez de dados binários de imagem. Como detectar: Decodifique uma vez — se o resultado se parece com outra string Base64 (começa com letras e termina com =), houve double encoding. Solução: Remover a etapa de encoding redundante no pipeline do backend.

Causa 10: Poluição por escape JSON ou URL-encoding

Strings Base64 contêm /. Alguns serializadores JSON escapam como \/. Se o frontend lê o JSON bruto sem parseá-lo corretamente (JSON.parse), as barras invertidas extras corrompem os dados. Da mesma forma, passar Base64 por parâmetros de URL sem encoding transforma + em espaços e remove os = de padding. Solução: Sempre usar JSON.parse() para dados JSON. Para transporte via URL, usar encodeURIComponent().

Template de depuração sistemática

Quando você travar, siga este processo passo a passo para isolar o problema:

1. Testar o data URI na barra de endereço — Cole a string completa data:image/...;base64,... diretamente na barra de endereço do navegador. Se a imagem renderizar, o problema está na forma como sua aplicação injeta a string.
2. Verificar o console do navegador — Pressione F12 e procure por erros como net::ERR_INVALID_URL ou violações de CSP na aba Console.
3. Verificar o tamanho da string — Compare o tamanho da string Base64 na origem (backend) com o que chega no frontend. Uma diferença indica truncamento ou corrupção em trânsito.
4. Decodificar e inspecionar — Use atob() no console para decodificar os primeiros caracteres. Se lançar InvalidCharacterError, a string contém caracteres inválidos.
5. Verificar double encoding — Decodifique uma vez. Se o resultado parecer outra string Base64, decodifique novamente. Se o segundo decode produzir dados binários, seu pipeline tem uma etapa de encoding a mais.

Valide seu Base64 instantaneamente com o ViewJSON

Em vez de inspecionar strings Base64 manualmente, cole seu JSON no ViewJSON. Ele detecta automaticamente mídias Base64 usando detecção de magic numbers e exibe previews inline — se o preview aparecer, seu Base64 está válido. Se não, você sabe exatamente qual campo está corrompido.