Résoudre "YAML parse error" et les problèmes courants d'indentation YAML : Un guide complet
YAML (YAML Ain't Markup Language) est apprécié pour son format lisible par l'homme et sa syntaxe épurée. C'est le standard pour la configuration dans des outils comme Kubernetes, Docker Compose, GitHub Actions et de nombreux générateurs de sites statiques. Cependant, YAML est notoirement strict concernant les espaces et l'indentation. Un seul espace au mauvais endroit peut entraîner une erreur invalid YAML ou YAML parse error difficile à localiser.
Dans ce guide, nous explorerons les erreurs YAML les plus courantes et comment les corriger rapidement.
1. Messages d'erreur YAML courants
Selon votre analyseur (comme js-yaml ou le PyYAML de Python), vous pourriez voir :
YAML parse error: bad indentation of a mapping entry(mauvaise indentation)YAML parse error: found character '\t' that cannot start any token(utilisation de YAML tab character)invalid YAML: mapping values are not allowed here(valeurs de mappage non autorisées)YAML parse error: duplicate key "..."(duplicate key in YAML / clé en double)YAML syntax error: end of stream loss
2. Principales causes et solutions
2.1 Erreurs d'indentation (YAML indentation error)
YAML utilise l'indentation pour définir la structure (comme les accolades {} en JSON). Elle doit être cohérente.
L'erreur :
services:
web:
image: nginx
ports: # Mauvaise indentation (3 espaces au lieu de 2 ou 4)
- "80:80"
La solution : Assurez-vous que tous les éléments de même niveau dans un mappage ou une liste ont exactement le même nombre d'espaces au début. L'utilisation de 2 espaces est la norme de l'industrie.
2.2 Caractères de tabulation (YAML tab character)
YAML interdit strictement l'utilisation du caractère de tabulation (\t) pour l'indentation. Vous DEVEZ utiliser des espaces.
L'erreur :
found character '\t' that cannot start any token
La solution :
Configurez votre éditeur de code (VS Code, Sublime, etc.) pour "Convertir les tabulations en espaces". Si vous avez déjà collé du code avec des tabulations, utilisez "Rechercher et remplacer" pour remplacer \t par .
2.3 Clés en double (duplicate key in YAML)
Contrairement à d'autres formats, YAML ne permet pas qu'une même clé apparaisse deux fois au même niveau d'un mappage.
L'erreur :
image: nginx
ports:
- "80:80"
image: alpine # Clé en double !
La solution : Vérifiez votre configuration pour détecter d'éventuels doublons accidentels, en particulier dans les fichiers volumineux ou lors de la fusion de plusieurs fichiers.
2.4 Espace manquant après les deux-points
Un piège courant en YAML est d'oublier l'espace après les deux-points (:) qui séparent une clé et sa valeur.
L'erreur :
url:https://example.com (YAML pense qu'il s'agit d'une seule longue chaîne)
La solution :
Incluez toujours un espace : url: https://example.com.
2.5 Chaînes multi-lignes
Si vous devez inclure une longue chaîne ou un bloc de code, vous devez utiliser les indicateurs scalaires de bloc corrects : | (conserve les sauts de ligne) ou > (replie les sauts de ligne).
L'erreur :
description: Ceci est une
très longue chaîne
sans indicateurs. # Cela provoquera une erreur d'analyse
La solution :
description: |
Ceci est une
très longue chaîne
qui préserve les sauts de ligne.
3. Dépannage avancé
3.1 Caractères spéciaux dans les valeurs
Si votre valeur contient des caractères tels que :, {, }, [, ], ,, &, *, #, ?, |, -, <, >, =, !, %, @, `, cela pourrait dérouter l'analyseur.
Solution : Enveloppez toute la valeur entre guillemets doubles ("...") ou guillemets simples ('...').
3.2 Pièges des booléens
En YAML 1.1, les valeurs telles que yes, no, on, off sont automatiquement converties en booléens (true/false). Cela peut poser problème si vous vouliez réellement la chaîne "no" (comme un code pays).
Solution : Mettez toujours ces chaînes entre guillemets : country: "NO".
4. Prévention et bonnes pratiques
- Utiliser un Linter YAML : Installez un linter dans votre éditeur (par exemple,
vscode-yamlde Red Hat) pour détecter les erreurs en temps réel. - Validation par schéma : Pour les formats spécifiques comme Kubernetes ou Docker Compose, utilisez leurs schémas JSON/YAML officiels pour la validation.
- Conversion automatisée : Si vous êtes plus à l'aise avec JSON, écrivez votre configuration en JSON et convertissez-la en YAML à l'aide d'un outil.
- Espacement cohérent : Standardisez à 2 espaces pour tous les fichiers YAML de votre projet.
5. FAQ : Foire aux questions
Q : Pourquoi mon YAML est-il valide dans un analyseur mais pas dans un autre ?
R : Il existe deux versions principales de YAML : 1.1 et 1.2. Certains analyseurs (comme PyYAML) utilisent par défaut la version 1.1, tandis que d'autres utilisent la version 1.2. La version 1.2 est plus compatible avec JSON. Si vous rencontrez des problèmes, essayez d'ajouter %YAML 1.2 en haut de votre fichier.
Q : Puis-je utiliser des commentaires en YAML ?
R : Oui ! C'est l'un des grands avantages de YAML par rapport au JSON. Utilisez le symbole # pour les commentaires.
Q : Comment échapper un guillemet simple à l'intérieur d'une chaîne entre guillemets simples ?
R : En YAML, vous échappez un guillemet simple en le doublant : 'It''s a beautiful day'.
6. Outil de vérification rapide
Vous avez du mal à trouver cette tabulation invisible ou ce mauvais espace ? Utilisez notre Validateur et Formateur YAML (prend en charge la conversion YAML vers JSON et la validation). Il peut :
- Mettre en évidence les erreurs de syntaxe avec les numéros de ligne.
- Convertir automatiquement les tabulations en espaces.
- Embellir le YAML désordonné pour une meilleure lisibilité.
Erreurs associées
- Résoudre les erreurs 'Unexpected token in JSON'
- Comment corriger les erreurs 'invalid base64 string'
- Comprendre les problèmes d'encodage de caractères