¿Tu imagen Base64 no se muestra? 10 causas frecuentes y cómo solucionarlas

Codificaste la imagen en Base64, pegaste el data URI en tu HTML y… nada. Solo aparece el ícono de imagen rota. Peor aún: funciona en Chrome pero falla en Safari, va perfecto en local pero se rompe en producción.

Los errores con imágenes Base64 son frustrantes porque la cadena parece correcta a simple vista. La causa real suele estar oculta en un detalle sutil: un carácter faltante en el prefijo, espacios invisibles inyectados al copiar y pegar, o un backend que silenciosamente codificó dos veces tus datos. Esta guía cubre las 10 causas más comunes con ejemplos de código y soluciones.

Referencia rápida: Síntoma → Causa → Solución

Empieza aquí. Encuentra tu síntoma, identifica la causa probable y salta a la solución detallada más abajo.

Errores de prefijo: el data: URI está mal formado

El esquema data URI tiene una sintaxis estricta. Un solo carácter incorrecto y el navegador trata tu cadena Base64 como una URL rota.

Causa 1: Falta todo el prefijo data URI

Si asignas la cadena Base64 directamente a src sin el prefijo data:image/...;base64,, el navegador la interpreta como una ruta URL relativa y el resultado es un 404.

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

Causa 2: Punto y coma escrito como coma

Escribir data:image/png,base64,... en lugar de data:image/png;base64,... hace que el navegador trate base64,... como texto plano.

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

Causa 3: Falta la coma después de "base64"

La coma entre base64 y los datos es obligatoria. Sin ella — data:image/png;base64iVBOR... — el navegador interpreta base64iVBOR... como nombre de charset.

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

Corrupción de codificación: la cadena Base64 en sí está rota

Incluso con un prefijo correcto, los datos codificados pueden corromperse silenciosamente durante el almacenamiento, la transmisión o al copiar y pegar.

Causa 4: Cadena truncada

Columnas con límite de caracteres (ej., VARCHAR(65535)) cortan silenciosamente las cadenas Base64. Un PNG de 100KB produce ~136.000 caracteres. Si se trunca a 65.535, la imagen queda rota. Solución: Usa TEXT o LONGTEXT.

Causa 5: Caracteres ilegales (espacios, caracteres especiales)

Base64 válido solo usa A-Z, a-z, 0-9, +, / y =. Espacios al copiar provocan InvalidCharacterError en atob(). Solución: str.replace(/\s/g, '').

Causa 6: Contaminación por saltos de línea

openssl base64 inserta \n cada 76 caracteres (RFC 2045). Estos saltos rompen los data URIs. Solución: Usa openssl base64 -A o elimina saltos: str.replace(/[\r\n]/g, '').

Causa 7: El padding se pierde al parsear la URL

Los = de padding suelen desaparecer en parámetros URL (= es reservado). Algunos navegadores toleran su ausencia, otros no. Solución: encodeURIComponent() antes de incluir en URL, o re-pad en el receptor.

MIME incorrecto: ¿realmente se rompe?

Sorprendentemente, declarar un MIME incorrecto normalmente no rompe la imagen.

Causa 8: El MIME declarado no coincide con el tipo real

Con data:image/png;base64,/9j/4AAQ... (JPEG con MIME de PNG), la mayoría de navegadores renderizan correctamente gracias al content sniffing. Falla en: (1) CSP estricto con verificación MIME, (2) servidor que confía en el MIME para conversión. Veredicto: Corrígelo, pero rara vez es la causa.

Errores de pipeline: los datos se corrompen antes de llegar al navegador

Son los más difíciles de diagnosticar: la cadena se ve correcta en tu código, pero la corrupción ocurre durante la serialización o transmisión.

Causa 9: Doble codificación Base64

Un backend que codifica datos ya codificados produce el Base64 de un Base64. El resultado es ~33% más largo y al decodificar una vez obtienes texto, no binario. Detección: Decodifica una vez — si parece otro Base64 (letras + =), es doble codificación. Solución: Elimina el paso redundante.

Causa 10: Contaminación por escape JSON o URL-encoding

Base64 contiene /. Algunos serializadores lo escapan como \/. Sin JSON.parse, las barras extra corrompen los datos. En URL, + se convierte en espacio y = desaparece. Solución: Usa JSON.parse() y encodeURIComponent().

Plantilla de depuración sistemática

Si ninguna causa anterior aplica, sigue estos pasos:

1. Prueba el data URI en la barra de direcciones — Pega la cadena completa. Si se renderiza, el problema está en cómo tu app inyecta la cadena.
2. Revisa la consola del navegador — F12, busca net::ERR_INVALID_URL o violaciones CSP.
3. Verifica la longitud — Compara la longitud en el backend vs. frontend. Si difieren, hubo truncamiento.
4. Decodifica e inspecciona — Usa atob() en la consola. Si lanza InvalidCharacterError, hay caracteres ilegales.
5. Detecta doble codificación — Decodifica una vez. Si el resultado parece Base64, decodifica de nuevo. Si sale binario, tu pipeline tiene un paso extra.

Valida Base64 al instante con ViewJSON

En vez de inspeccionar manualmente, pega tu JSON en ViewJSON. Detecta medios Base64 mediante números mágicos y muestra vistas previas integradas — si aparece, tu Base64 es válido.