Image Base64 qui ne s'affiche pas ? 10 causes fréquentes et leurs solutions

Vous avez encodé une image en Base64, collé le data URI dans votre HTML, et… rien. Une icône d'image cassée vous fixe. Pire encore : ça fonctionne dans Chrome mais pas dans Safari, ou en local mais pas en production.

Les erreurs d'images Base64 sont frustrantes parce que la chaîne a l'air correcte au premier coup d'œil. La vraie cause se cache en général dans un détail subtil : un caractère manquant dans le préfixe, des espaces invisibles introduits par un copier-coller, ou un backend qui a silencieusement double-encodé vos données. Ce guide couvre les 10 causes les plus courantes avec des exemples de code et des correctifs.

Référence rapide : Symptôme → Cause → Solution

Commencez ici. Repérez votre symptôme, identifiez la cause probable et sautez directement à la solution détaillée plus bas.

Erreurs de préfixe : le data: URI est malformé

Le schéma data URI a une syntaxe stricte. Un seul caractère erroné et le navigateur traite votre chaîne Base64 comme une URL cassée au lieu de données image.

Cause 1 : Le préfixe data URI est totalement absent

Si vous affectez directement la chaîne Base64 brute à src sans le préfixe data:image/...;base64,, le navigateur l'interprète comme un chemin d'URL relatif — résultat : une 404.

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

Cause 2 : Point-virgule écrit comme une virgule

Écrire data:image/png,base64,... au lieu de data:image/png;base64,... amène le navigateur à traiter base64,... comme du texte brut plutôt que comme un indicateur d'encodage Base64.

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

Cause 3 : Virgule manquante après "base64"

La virgule entre base64 et les données est obligatoire. Sans elle — data:image/png;base64iVBOR... — le navigateur lit base64iVBOR... comme un nom de charset, pas comme des données encodées.

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

Corruption d'encodage : la chaîne Base64 elle-même est cassée

Même avec un préfixe correct, le contenu encodé peut être silencieusement corrompu lors du stockage, du transfert ou d'un copier-coller.

Cause 4 : Chaîne tronquée

Les colonnes limitées en caractères ou en octets (par ex. VARCHAR(65535)) peuvent tronquer les chaînes Base64. Un PNG de 100 Ko génère environ 136 000 caractères. Une coupure à 65 535 octets produit une image corrompue au décodage. Solution : choisir un type assez grand pour la base et l'encodage, par exemple MEDIUMTEXT ou LONGTEXT sous MySQL, et détecter toute troncature.

Cause 5 : Caractères illégaux (espaces, caractères spéciaux)

Un Base64 valide n'utilise que A-Z, a-z, 0-9, +, / et =. Les espaces introduits par un copier-coller font planter atob() avec InvalidCharacterError. Solution : Supprimer tous les espaces avant utilisation : str.replace(/\s/g, '').

Cause 6 : Pollution par les retours à la ligne

Des outils comme openssl base64 insèrent un \n tous les 76 caractères par défaut (RFC 2045). Ces sauts de ligne cassent les data URIs dans le HTML. Solution : Utiliser openssl base64 -A (sortie sur une seule ligne) ou supprimer les retours à la ligne : str.replace(/[\r\n]/g, '').

Cause 7 : Padding supprimé lors du passage en URL

Les caractères de padding comme = peuvent être mal traités dans des paramètres d'URL ou de formulaire ; le + peut aussi arriver comme un espace. Solution : encoder la valeur avant de l'ajouter à l'URL, utiliser un Base64 compatible URL si nécessaire et valider le padding à la réception.

Type MIME incorrect : est-ce que ça casse vraiment ?

Ça surprend beaucoup de développeurs : un type MIME erroné ne casse généralement pas l'affichage de l'image.

Cause 8 : Le MIME déclaré ne correspond pas au type réel du fichier

Avec data:image/png;base64,/9j/4AAQ... (données JPEG déclarées comme PNG), un navigateur peut quand même afficher l'image, mais le résultat dépend du consommateur et de sa gestion du type MIME. Des clients stricts ou une conversion côté serveur peuvent échouer. Verdict : corriger le MIME et vérifier les octets réels ; c'est une cause possible, pas universelle.

Erreurs de pipeline : données corrompues avant d'arriver au navigateur

Ce sont les cas les plus difficiles à diagnostiquer car la chaîne Base64 semble correcte dans votre code — la corruption a lieu pendant la sérialisation ou la transmission.

Cause 9 : Double encodage Base64

Un backend qui encode des données déjà encodées produit le Base64 d'une chaîne Base64. Le résultat est ~33% plus long que prévu et, après un seul décodage, vous obtenez du texte au lieu de données binaires d'image. Comment détecter : Décodez une fois — si le résultat ressemble à une autre chaîne Base64 (commence par des lettres et se termine par =), vous avez un double encodage. Solution : Supprimer l'étape d'encodage superflue dans votre pipeline backend.

Cause 10 : Pollution par l'échappement JSON ou l'URL-encoding

Les valeurs Base64 peuvent être altérées si le JSON sérialisé ou les données URL sont traités comme du texte brut. \/ ne pose pas problème après un JSON.parse() correct, mais un formulaire peut convertir + en espace. Solution : parser le JSON, encoder les valeurs URL et valider les octets décodés.

Template de débogage systématique

Quand vous êtes bloqué, suivez cette procédure pas à pas pour isoler le problème :

1. Tester le data URI dans la barre d'adresse — Collez la chaîne complète data:image/...;base64,... directement dans la barre d'adresse du navigateur. Si l'image s'affiche, le problème vient de la façon dont votre application injecte la chaîne.
2. Vérifier la console du navigateur — Appuyez sur F12 et cherchez des erreurs comme net::ERR_INVALID_URL ou des violations CSP dans l'onglet Console.
3. Vérifier la longueur de la chaîne — Comparez la longueur de la chaîne Base64 à la source (backend) avec celle reçue côté frontend. Un écart signifie une troncature ou une corruption en transit.
4. Décoder et inspecter — Utilisez atob() dans la console pour décoder les premiers caractères. Si ça lève InvalidCharacterError, la chaîne contient des caractères illégaux.
5. Vérifier le double encodage — Décodez une fois. Si le résultat ressemble à une autre chaîne Base64, décodez à nouveau. Si le second décodage produit des données binaires, votre pipeline a une étape d'encodage en trop.

Validez votre Base64 instantanément avec ViewJSON

Au lieu d'inspecter manuellement les chaînes Base64, collez votre JSON dans ViewJSON. Il détecte automatiquement les médias encodés en Base64 par détection de magic numbers et affiche des aperçus intégrés — si l'aperçu s'affiche, votre Base64 est valide. Sinon, vous savez exactement quel champ est corrompu.