BOM UTF-8 : corriger les erreurs JSON.parse et CSV

Une erreur d’analyse JSON causée par un BOM UTF-8, ce sont trois octets que vous ne voyez pas. Le fichier s’ouvre proprement dans votre éditeur, cat affiche exactement ce que vous attendiez, votre linter ne dit rien, et JSON.parse lève quand même une exception dès le tout premier caractère.

Mesurée sur node v25.8.2, l’exception ressemble à ceci :

SyntaxError: Unexpected token '', "{"a":1}" is not valid JSON

Quoi que votre terminal ait dessiné entre ces guillemets, il s’agit d’un seul caractère : U+FEFF, stocké sous la forme des octets EF BB BF. Le JSON strict ne lui réserve aucune place. À la position 0, un analyseur attend {, [, un chiffre, un guillemet ou une espace, et U+FEFF n’est rien de tout cela.

Si vous savez déjà qu’il s’agit d’un BOM, choisissez le côté que vous maîtrisez :

Là où vous pouvez agir	Le correctif
Node, à la lecture d’un fichier	JSON.parse(raw.replace(/^/, ''))
Python, à la lecture d’un fichier	open(path, encoding='utf-8-sig')
Le fichier sur le disque	tail -c +4 data.json > clean.json

Le reste de cette page couvre les cas où cela ne suffit pas : l’erreur qui ressemble à un BOM sans en être un, la source qui le remet en place à chaque fois, et le seul format qui a besoin qu’on le garde. Pour savoir ce qu’est un BOM et si un nouveau fichier doit en porter un, le guide complet de l’encodage UTF-8 vs UTF-16 vs Unicode traite déjà le sujet. Cette page part du principe que le vôtre a déjà cassé quelque chose.

Les mesures ci-dessous viennent toutes de node v25.8.2 et Python 3.14.5.

1. Ce que votre erreur élimine avant d’accuser le BOM

La plupart des gens qui cherchent une erreur JSON en position 0 n’ont pas de BOM. Quatre problèmes distincts produisent un message de même forme, et un coup d’œil au caractère cité suffit à les séparer. Voici les chaînes littérales qu’émet V8 :

Texte de l’erreur	Ce dont il s’agit réellement	Étape suivante
Unexpected token '', "{"a":1}" is not valid JSON	Un BOM UTF-8 à l’octet 0	Section 2
Unexpected token '<', "<!DOCTYPE "... is not valid JSON	La réponse était du HTML : une page d’erreur, une redirection vers un formulaire de connexion, un message de proxy	Journalisez le corps brut et le code de statut
Unexpected end of JSON input	Le corps était vide	Vérifiez le code de statut et Content-Length
"undefined" is not valid JSON	Vous avez passé à JSON.parse une variable jamais affectée	Corrigez l’appelant

La règle est courte. Lisez le caractère placé entre les apostrophes. < veut dire que vous avez reçu du HTML. Un carré, un blanc ou un point d’interrogation que vous n’arrivez pas à sélectionner, c’est U+FEFF. Et si les guillemets sont vides, il n’y avait pas d’entrée au départ.

L’ancienne formulation et la nouvelle

Les résultats de recherche pour json parse unexpected token position 0 décrivent pour la plupart un ancien message de V8 :

SyntaxError: Unexpected token in JSON at position 0

Cette formulation nommait la position et masquait le caractère. La formulation actuelle fait l’inverse : elle montre le caractère et un extrait de l’entrée, ce qui est bien plus utile, mais cela signifie que la page sur laquelle vous atterrissez décrit peut-être un runtime que vous n’utilisez pas. Si votre erreur nomme encore une position plutôt qu’un caractère, vous êtes sur un moteur plus ancien et le diagnostic ci-dessous reste identique.

2. Confirmer qu’il s’agit d’un BOM en dix secondes

Quatre vérifications, classées à peu près par rapidité. N’importe laquelle tranche la question.

Regardez les trois premiers octets.

$ hexdump -C data.json | head -1
00000000  ef bb bf 7b 22 61 22 3a  31 7d                    |...{"a":1}|

ef bb bf avant le 7b ({), c’est le BOM. Les ... dans la colonne ASCII à droite, c’est hexdump qui signale n’avoir rien d’imprimable à afficher.

Interrogez file. Il vous le dit directement, et il change complètement d’avis sur le type du fichier :

$ file data.json
data.json: Unicode text, UTF-8 (with BOM) text, with no line terminators

$ file clean.json
clean.json: JSON data

Vérifiez le premier codepoint dans Node.

const fs = require('fs');
const raw = fs.readFileSync('data.json', 'utf8');
console.log(raw.charCodeAt(0) === 0xFEFF);   // true

Lisez la barre d’état de l’éditeur. VS Code affiche UTF-8 with BOM dans le coin inférieur droit, et un clic dessus propose Save with encoding. Cette étiquette explique à elle seule pourquoi le fichier avait l’air correct : l’éditeur connaissait l’encodage et le signalait dans un coin de la fenêtre.

Pour une vue au niveau octet de quelque chose que vous ne pouvez pas dumper en local, collez-le dans l’Encodeur et Décodeur Base64 en ligne. Un BOM UTF-8 en tête de charge utile s’encode toujours en une chaîne qui commence par 77u/, un motif facile à repérer dans une ligne de log.

3. D’où vient votre BOM

Supprimer le BOM d’un fichier qu’une étape de build régénère toutes les heures, c’est un correctif dont l’espérance de vie est d’une heure. Les producteurs habituels :

• L’option Enregistrer sous → CSV UTF-8 d’Excel. Celle-là est délibérée, ce n’est pas un bug, et la section 7 explique pourquoi.
• Le Bloc-notes et les autres éditeurs Windows qui proposent UTF-8 avec BOM comme option d’enregistrement distincte, parfois même par défaut.
• VS Code, quand files.encoding vaut utf8bom, que ce soit dans vos réglages utilisateur ou dans un .vscode/settings.json versionné que personne ne va regarder.
• La redirection shell sous PowerShell. > et Out-File écrivent un BOM par défaut dans certaines versions de PowerShell, et ce comportement par défaut diffère entre la branche 5.x réservée à Windows et la branche multiplateforme 6/7. Ne vous fiez pas à votre mémoire là-dessus : écrivez un fichier et vérifiez ses trois premiers octets avec les commandes de la section 2.
• Le code d’export écrit à la main. Tout code qui écrit de l’UTF-8 sans préciser s’il faut émettre une signature hérite du choix par défaut de son framework, et les frameworks n’ont pas tous fait le même choix. Les vieux chemins d’export .NET et Java sont les suspects habituels.
• Les outils d’export de bases de données et de BI, qui livrent souvent un BOM parce que leur consommateur principal est un tableur.

Si le fichier vous arrive d’un partenaire ou d’un fournisseur et que vous ne pouvez pas changer le producteur, passez à la section 4 et supprimez le BOM à la lecture. S’il vient de votre propre dépôt, la section 9 est la réponse durable.

4. Le corriger en JavaScript et dans Node

C’est ici que la confusion se concentre, parce que l’écosystème JavaScript n’a pas une politique unique vis-à-vis du BOM. Il en a plusieurs, et elles se contredisent. Même fichier, même runtime, mesuré sur node v25.8.2 :

API	Comportement vis-à-vis du BOM	JSON.parse ensuite
fetch → res.json()	supprimé	réussit
fs.readFileSync(f, 'utf8')	conservé	échoue
new TextDecoder() (par défaut)	supprimé	réussit
new TextDecoder('utf-8', { ignoreBOM: true })	conservé	échoue
require('./data.json')	supprimé	sans objet, déjà analysé
import(..., { with: { type: 'json' } })	supprimé	sans objet, déjà analysé

Deux choses ressortent de ce tableau, et chacune coûte des après-midi entiers.

ignoreBOM fait l’inverse de ce qu’il annonce

ignoreBOM: true ne veut pas dire « ignorer le BOM ». Cela veut dire « ignorer la signification particulière du BOM et le conserver comme un caractère ordinaire ». C’est la valeur par défaut, false, qui le supprime. Le nom décrit ce que le décodeur ignore, pas ce que vous récupérez ; le lire dans son sens naturel donne un décodeur qui conserve précisément l’octet que vous cherchiez à supprimer.

Pourquoi ça marche dans le navigateur et casse dans Node

C’est de loin la variante la plus signalée du problème : la même URL JSON s’analyse sans souci dans le code front-end et lève une exception dès qu’un script Node lit le fichier sur le disque. Rien n’a changé dans le fichier. res.json() décode par la même mécanique que TextDecoder et laisse tomber le BOM au passage ; fs.readFileSync(path, 'utf8') est un décodage fidèle qui vous rend chaque caractère contenu dans le fichier, U+FEFF compris.

La même asymétrie explique pourquoi require('./config.json') fonctionne alors que JSON.parse(fs.readFileSync('./config.json', 'utf8')) échoue. Le chargeur de modules JSON de Node supprime le BOM ; le chemin manuel, non.

Le supprimer

const fs = require('fs');
const raw = fs.readFileSync('data.json', 'utf8');
const data = JSON.parse(raw.replace(/^/, ''));

Ancrez le motif avec ^. Un remplacement global sans ancrage supprimerait aussi les caractères U+FEFF légitimes à l’intérieur des valeurs de chaîne, ce qui revient à perdre des données.

Une solution de rechange plus discrète, qui marche par accident : JSON.parse(raw.trim()) réussit également, parce qu’ECMAScript classe U+FEFF parmi les espaces blancs et que String.prototype.trim le supprime. Le comportement est réel, mais il tient à une particularité de la spécification JavaScript et ne se transpose pas aux autres langages. Le str.strip() de Python, lui, laisse un U+FEFF exactement là où il l’a trouvé.

Si vous voulez confirmer que le résultat nettoyé est réellement valide et pas seulement exempt d’exception, collez-le dans le Formateur JSON en ligne. Une fois le BOM parti, les candidats qui restent en position 0 sont les problèmes d’échappement ordinaires que couvre le guide Échapper une chaîne JSON.

5. Le corriger en Python : utf-8-sig

Python est le seul runtime qui nomme le problème dans son message d’erreur. Ouvrez un fichier préfixé d’un BOM comme de l’UTF-8 ordinaire et json vous donne le diagnostic et le correctif d’un même souffle :

JSONDecodeError: Unexpected UTF-8 BOM (decode using utf-8-sig): line 1 column 1 (char 0)

Si vous avez cherché unexpected utf-8 bom et atterri ici, c’est de là que vient cette chaîne. Le codec qu’elle désigne lit le BOM comme une signature et le jette :

import json

with open('data.json', encoding='utf-8-sig') as f:
    data = json.load(f)

utf-8-sig est sans danger sur les fichiers qui n’ont pas de BOM. Il en supprime un s’il est présent et se comporte comme de l’UTF-8 ordinaire sinon, ce qui en fait le bon choix par défaut pour tout fichier que vous n’avez pas produit vous-même.

Les octets et le texte ne se comportent pas de la même façon

Une asymétrie qu’il vaut mieux connaître, parce qu’elle fait passer le bug pour intermittent :

import json

json.loads(open('data.json', 'rb').read())       # {'a': 1}      works
json.loads(open('data.json', encoding='utf-8').read())  # raises the error above

json.loads sur des bytes commence par une étape de détection d’encodage, repère le BOM et décode avec utf-8-sig à votre place. Donnez-lui un str déjà décodé et il n’y a plus rien à détecter : le U+FEFF arrive jusqu’à l’analyseur. Les deux chemins de code semblent équivalents, mais un seul règle le problème en silence.

Écrire un BOM délibérément

Le même codec fonctionne dans l’autre sens, et c’est ainsi qu’on produit un fichier pour Excel :

with open('report.csv', 'w', encoding='utf-8-sig', newline='') as f:
    f.write('name\n')

Ce fichier commence par ef bb bf. La section 7 explique quand c’est bien ce que vous voulez.

Le piège du CSV

csv.DictReader sur un texte préfixé d’un BOM fait exactement ce qu’un analyseur CSV correct doit faire, et produit une clé que personne n’arrive à faire correspondre :

import csv, io

data = 'name,age\nAlice,30\n'
print(list(next(csv.DictReader(io.StringIO(data))).keys()))
# ['name', 'age']

Votre première colonne ne s’appelle pas name. C’est U+FEFF suivi de name, et chaque accès row['name'] lève une KeyError alors que l’en-tête s’affiche correctement dans n’importe quel débogueur. Ouvrir le fichier avec encoding='utf-8-sig' le supprime avant même que le lecteur ne le voie.

6. Supprimer le BOM en Java, Go, PHP et dans le shell

Chaque correctif est le même correctif à une altitude différente : supprimer trois octets (EF BB BF) ou supprimer un caractère (U+FEFF), selon que vous tenez des octets ou du texte. Si votre langage n’a pas de codec qui gère le BOM, faites-le à la main.

Java décode le BOM en un caractère  de tête :

String text = Files.readString(path, StandardCharsets.UTF_8);
if (!text.isEmpty() && text.charAt(0) == '') {
    text = text.substring(1);
}

Go, au niveau octet, avant le décodage :

raw, err := os.ReadFile("data.json")
if err != nil {
    return err
}
raw = bytes.TrimPrefix(raw, []byte{0xEF, 0xBB, 0xBF})

var v map[string]any
err = json.Unmarshal(raw, &v)

PHP, avec un motif ancré sur les octets :

$raw  = file_get_contents('data.json');
$raw  = preg_replace('/^\xEF\xBB\xBF/', '', $raw);
$data = json_decode($raw, true);

Pour supprimer le BOM d’un fichier plutôt que d’une variable, voici quatre commandes toutes vérifiées sur un fichier commençant par ef bb bf :

# In place, GNU sed (Linux). The shell expands the escapes, not sed.
sed -i $'1s/^\xEF\xBB\xBF//' data.json

# In place, BSD sed (macOS)
sed -i '' $'1s/^\xEF\xBB\xBF//' data.json

# In place, anywhere Perl exists. First line only.
perl -i -pe 's/^\x{ef}\x{bb}\x{bf}// if $. == 1' data.json

# Copy without the first three bytes. Only safe if you know a BOM is there.
tail -c +4 data.json > clean.json

La forme avec tail est la plus brutale : elle retire trois octets, que ces octets aient été un BOM ou non. Confirmez d’abord avec la section 2.

7. L’exception CSV : quand Excel a besoin qu’on garde le BOM

Tout ce qui précède traite le BOM comme un problème. À un endroit, il porte une information, et le supprimer casse un fichier qui fonctionnait.

Les recherches sur csv bom excel se répartissent en deux plaintes opposées, ce qui montre bien qu’une même règle s’applique dans le mauvais sens :

1. « Mon CSV s’ouvre dans Excel avec é et æ¥æ¬èª au lieu des vrais caractères. » Le BOM manque.
2. « Ma première colonne s’appelle name et mon script n’arrive pas à la trouver. » Le BOM est présent.

Pourquoi Excel en a besoin

Excel sous Windows n’a aucun moyen fiable de savoir qu’un CSV est en UTF-8. Pas d’en-tête, aucune déclaration d’encodage : un fichier .csv, ce sont des octets. Faute de signal, il retombe sur la locale du système, donc Windows-1252 aux États-Unis et en Europe de l’Ouest, Windows-1251 en Russie, et tous les caractères non ASCII ressortent faux. Le BOM est ce signal. Trois octets en tête, et Excel lit correctement l’UTF-8.

En CSV, le BOM est donc une fonctionnalité, et la décision tient en une ligne :

Écrit pour être analysé par une machine : supprimez le BOM. Écrit pour qu’un humain double-clique dessus dans Excel : gardez-le.

La panne de l’autre côté

Donnez le même fichier à un analyseur et le BOM se fond dans votre première cellule d’en-tête. Dans Node :

const header = 'name,age'.split(',');
console.log(JSON.stringify(header));   // ["name","age"]

const row = { 'name': 'Alice', age: 30 };
console.log(row.name);                 // undefined

row.name vaut undefined alors que la clé s’affiche name dans vos logs, dans votre débogueur et dans votre console.table. C’est un bug de la même forme que la KeyError Python de la section 5, et c’est pourquoi « le nom du champ correspond mais la valeur manque » doit vous faire penser au BOM dès le premier coup d’œil.

Nos convertisseurs traitent délibérément les deux cas. Le Convertisseur CSV vers JSON en ligne supprime un BOM de tête dans l’entrée avant l’analyse, si bien qu’un fichier sorti tout droit d’Excel produit name et non name. Dans l’autre sens, le Convertisseur JSON vers CSV en ligne fait du BOM une option explicite, et son préréglage Excel l’active en même temps qu’un délimiteur point-virgule et des fins de ligne CRLF, la combinaison dont les locales Excel européennes ont réellement besoin. Pour les autres décisions de conversion (délimiteurs, guillemets, inférence de types), le guide Conversion CSV en JSON : méthodes, pièges et exemples de code détaille la marche à suivre.

8. Au-delà de JSON : où un BOM se manifeste encore

JSON le fait savoir bruyamment. Les autres formats, non.

Les scripts shell. Un BOM s’intercale entre le début du fichier et le #!, si bien que le noyau ne voit jamais de shebang et ne lance jamais votre interpréteur. Sur macOS, le résultat mesuré était un repli du shell sur sh, qui signalait la ligne du shebang comme un fichier introuvable :

./bom.sh: line 1: #!/bin/sh: No such file or directory

Le script s’est ensuite exécuté quand même, sous le mauvais interpréteur, ce qui est pire qu’un échec. D’autres systèmes le formulent autrement ; l’erreur bad interpreter en est la variante la plus connue. Si un script qui commence par un #!/usr/bin/env python3 parfaitement correct insiste pour dire que ce chemin n’existe pas, allez voir les octets.

PHP. Tout ce qui se trouve hors de <?php ... ?> est de la sortie, et un BOM avant la balise ouvrante, ce sont trois octets de sortie envoyés avant que votre code ne s’exécute. Le premier appel à header(), session_start() ou setcookie() échoue alors avec le classique avertissement headers already sent, qui pointe la ligne 1 d’un fichier dont la ligne 1 paraît vide.

Les fichiers .env et tout format clé-valeur. Mécanisme identique au cas du CSV : votre première variable n’est pas DATABASE_URL, c’est U+FEFF suivi de DATABASE_URL, donc la recherche échoue alors que le fichier se lit correctement pour un humain. Toutes les variables suivantes fonctionnent, ce qui donne l’impression d’un problème lié à un réglage bien précis.

XML est l’exception dans l’autre sens. La spécification XML autorise explicitement un BOM UTF-8 au début d’un document, au titre de la détection automatique d’encodage, et les analyseurs sont tenus de le gérer. Le xml.etree.ElementTree de Python a accepté sans broncher un document préfixé d’un BOM pendant les tests. Si votre XML échoue, ce n’est probablement pas à cause du BOM.

9. L’arrêter à la source

Une fois le mécanisme compris, retirer le BOM d’un fichier devient la partie facile. Reste à empêcher le fichier d’en récupérer un.

Figez l’encodage dans .editorconfig. La propriété charset accepte utf-8 et utf-8-bom comme deux valeurs distinctes, donc déclarer celle que vous voulez ne laisse aucune ambiguïté :

[*]
charset = utf-8

Vérifiez le réglage d’éditeur qui la surcharge. Dans VS Code, c’est "files.encoding": "utf8", et la valeur à surveiller est utf8bom. Inspectez le .vscode/settings.json du dépôt autant que vos réglages utilisateur, parce qu’un réglage d’espace de travail versionné s’applique en silence à toute l’équipe.

Passez un scan en CI ou dans un hook de pre-commit. Celui-ci est portable, n’a aucune dépendance, et renvoie un code de sortie non nul quand il trouve quelque chose :

#!/bin/sh
# Fail if any tracked file begins with EF BB BF
found=0
for f in $(git ls-files '*.json' '*.md' '*.sh'); do
  if [ "$(head -c3 "$f" | od -An -tx1 | tr -d '[:space:]')" = "efbbbf" ]; then
    echo "BOM: $f"
    found=1
  fi
done
exit $found

Vérifié dans les deux sens : il liste les chemins fautifs et sort avec 1 quand un fichier préfixé d’un BOM est suivi par git, et sort avec 0 une fois les fichiers propres.

Écrivez noir sur blanc la seule exception autorisée. Une règle du type « aucun BOM nulle part » saute la première fois que quelqu’un a besoin d’un export tableur, après quoi plus personne ne la respecte. Énoncez plutôt l’exception : les BOM sont permis dans les fichiers CSV générés pour Excel, nulle part ailleurs. Excluez le répertoire d’export du scanner et la règle survit au contact du réel.

10. Une bissection en soixante secondes

À dérouler dans l’ordre. Chaque étape termine l’enquête ou transmet à la suivante un problème plus petit.

1. Lisez le caractère, pas la position. Section 1. < veut dire du HTML, et vous en avez fini ici. Rien entre les guillemets, c’est un corps vide. Un carré illisible : continuez.
2. Confirmez les octets. hexdump -C file | head -1. Si les trois premiers octets ne sont pas ef bb bf, arrêtez-vous : ce n’est pas un BOM et rien de ce qui suit n’aidera.
3. Trouvez par où il entre. Le fichier est-il préfixé d’un BOM sur le disque, ou bien propre sur le disque et préfixé une fois arrivé dans votre code ? Un fichier propre sur le disque signifie que quelque chose dans votre pipeline l’ajoute.
4. Choisissez un seul côté à corriger. Supprimez à la lecture quand le producteur est un fournisseur, un téléversement ou une étape de build qui ne vous appartient pas. Corrigez le producteur quand il est à vous, parce que le correctif côté lecture doit être répété chez chaque lecteur.
5. Appliquez le correctif à la frontière de décodage, pas plus profond. encoding='utf-8-sig' à l’appel open(), pas un .lstrip() sur une chaîne trois fonctions plus loin. Le corriger au fond de la pile, c’est offrir au prochain chemin de code qui lira le fichier le plaisir de redécouvrir le bug.
6. Vérifiez que les octets ont changé. Rejouez l’étape 2. Un correctif qui marche dans un chemin de code sans avoir touché au fichier échouera dans le suivant.
7. Ajoutez le scanner. Section 9. Sinon vous recommencerez tout cela au prochain trimestre.

FAQ

Le BOM UTF-8 est-il obligatoire ?

Non. UTF-8 n’a qu’un seul ordre d’octets, il n’y a donc rien qu’une marque puisse désambiguïser. Unicode autorise un BOM UTF-8 comme signature d’encodage mais ne le recommande pas, et JSON l’interdit purement et simplement : la RFC 8259 énonce que les implémentations ne doivent pas ajouter de marque d’ordre des octets à un texte JSON.

Pourquoi le fichier a-t-il l’air correct dans mon éditeur alors que l’analyse échoue ?

Parce que U+FEFF ne s’affiche pas du tout. Les éditeurs qui le reconnaissent masquent le caractère et mentionnent UTF-8 with BOM dans la barre d’état à la place. Ceux qui ne le reconnaissent pas dessinent simplement zéro pixel. cat, less et un diff de revue de code affichent eux aussi exactement la même chose avec ou sans lui. Seule une vue au niveau octet le révèle.

JSON.parse supprime-t-il parfois le BOM automatiquement ?

Jamais. JSON.parse reçoit une chaîne et traite U+FEFF comme un caractère inattendu où qu’il apparaisse. Ce qui le supprime, c’est la couche au-dessus : res.json() après un fetch, le require() de Node pour les fichiers .json et TextDecoder dans ses réglages par défaut le retirent tous avant que l’analyseur ne voie quoi que ce soit.

Faut-il supprimer le BOM des fichiers CSV ?

Cela dépend de qui ouvre le fichier. N’importe quel analyseur intégrera le BOM au nom de votre première colonne, name devient donc name et tous les accès échouent. Là, supprimez-le. Excel sous Windows se sert du BOM pour détecter l’UTF-8 et massacre sans lui les caractères accentués et CJK. Là, gardez-le.

Le BOM est-il la même chose qu’une espace de largeur nulle ?

Même codepoint, rôle différent. U+FEFF à l’offset 0 est une marque d’ordre des octets. Partout ailleurs dans un document, c’est ZERO WIDTH NO-BREAK SPACE, un usage qu’Unicode a déprécié au profit de U+2060 WORD JOINER. D’anciens textes en contiennent encore, ce qui explique qu’on retrouve U+FEFF au beau milieu des fichiers.

Le BOM a-t-il un effet sur les diffs git et la taille des fichiers ?

Trois octets sur le disque, et une ligne parasite dans chaque diff qui y touche. Git compare des octets, donc ajouter ou supprimer un BOM réécrit la ligne 1 même quand le texte rendu est identique. C’est de là que vient la modification d’une seule ligne que personne n’arrive à expliquer en revue.