¿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

Las columnas con límite de caracteres o bytes (por ejemplo, VARCHAR(65535)) pueden truncar las cadenas Base64. Un PNG de 100 KB produce unos 136.000 caracteres. Si se corta en 65.535 bytes, la imagen decodificada queda dañada. Solución: elige un tipo suficientemente grande para tu base de datos y codificación, como MEDIUMTEXT o LONGTEXT en MySQL, y detecta el truncamiento.

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 caracteres de padding como = pueden procesarse mal en parámetros URL o formularios; + también puede llegar como espacio. Solución: codifica el valor antes de incluirlo en la URL, usa Base64 compatible con URL cuando corresponda y valida el padding al recibirlo.

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), un navegador puede renderizarlo, pero depende del consumidor y de cómo maneje el tipo MIME. Clientes estrictos o conversiones en servidor pueden fallar. Veredicto: corrige el MIME y verifica los bytes reales; es una causa posible, no universal.

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

Los valores Base64 pueden dañarse si el JSON serializado o los datos URL se tratan como texto sin procesar. \/ no es un problema después de usar JSON.parse(), pero en formularios + puede convertirse en espacio. Solución: analiza el JSON, codifica los valores URL y valida los bytes decodificados.

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.