Validation YAML Docker Compose : 10 erreurs de syntaxe courantes et comment les corriger

Les fichiers YAML Docker Compose semblent simples — jusqu'à ce qu'ils cassent. Un espace mal placé, une mauvaise indentation ou un caractère spécial non quoté provoque des erreurs cryptiques. Voici les 10 erreurs les plus courantes et comment les corriger.

Validez votre YAML avec notre convertisseur JSON-YAML →

Erreur 1 : Tabulations au lieu d'espaces

Message d'erreur :

yaml: line 5: found a tab character where an indentation space is expected

Problème : YAML interdit strictement les tabulations pour l'indentation.

Solution : Remplacez toutes les tabulations par des espaces (2 espaces par niveau).

# BAD (tabs - invisible but breaks YAML)
services:
	web:
		image: nginx

# GOOD (2 spaces)
services:
  web:
    image: nginx

Astuce éditeur : Activez "Render Whitespace" pour distinguer tabulations et espaces.

Erreur 2 : Indentation incohérente

Message d'erreur :

yaml: line 8: mapping values are not allowed in this context

Problème : Mélange de niveaux d'indentation (2 espaces ici, 4 là).

# BAD (inconsistent: 2 spaces then 4 spaces)
services:
  web:
      image: nginx     # 4 spaces - inconsistent!
      ports:
        - "80:80"

# GOOD (consistent 2 spaces)
services:
  web:
    image: nginx       # 2 spaces - consistent
    ports:
      - "80:80"

Erreur 3 : Caractères spéciaux non quotés

Message d'erreur :

yaml: line 6: did not find expected key

Problème : YAML interprète certains caractères. Colons, hashes et accolades doivent être quotés.

# BAD
services:
  web:
    environment:
      - DATABASE_URL=postgres://user:pass@db:5432/mydb  # colon in value!
      - APP_TITLE=My App: The Best                       # colon in value!

# GOOD (quote values with special characters)
services:
  web:
    environment:
      - "DATABASE_URL=postgres://user:pass@db:5432/mydb"
      - "APP_TITLE=My App: The Best"

Caractères à quoter : : { } [ ] , & * # ? | - < > = ! % @

Erreur 4 : Mauvais format de mapping de ports

Message d'erreur :

services.web.ports contains an invalid type, it should be a number, or an object

Problème : YAML peut interpréter 80:80 comme base-60 sans guillemets.

# RISKY (YAML may interpret as base-60)
services:
  web:
    ports:
      - 80:80        # Works but risky
      - 5432:5432    # May cause issues

# SAFE (always quote port mappings)
services:
  web:
    ports:
      - "80:80"
      - "5432:5432"
      - "127.0.0.1:3000:3000"

Erreur 5 : Clé version absente ou incorrecte

Message d'erreur :

(root) Additional property version is not allowed

Problème : Docker Compose v2 n'exige plus la clé version.

# OUTDATED (Docker Compose v1 format)
version: "3.8"
services:
  web:
    image: nginx

# CURRENT (Docker Compose v2 - no version needed)
services:
  web:
    image: nginx

Avec docker compose (v2) : supprimez version. Avec docker-compose (v1) : gardez-la.

Erreur 6 : Variables d'environnement mapping vs liste

Message d'erreur :

services.web.environment must be a mapping or an array

Problème : Mélange de syntaxe mapping et liste pour les variables d'environnement.

# Format A: List (with dashes)
services:
  web:
    environment:
      - NODE_ENV=production
      - PORT=3000

# Format B: Mapping (key: value)
services:
  web:
    environment:
      NODE_ENV: production
      PORT: 3000

# BAD: Mixing both formats
services:
  web:
    environment:
      NODE_ENV: production
      - PORT=3000          # ERROR: mixing formats!

Erreur 7 : Valeurs booléennes non quotées

Message d'erreur : Pas d'erreur visible, comportement inattendu.

Problème : YAML interprète yes, no, true, false, on, off comme booléens.

# BAD (YAML converts to boolean true/false)
services:
  web:
    environment:
      FEATURE_FLAG: yes       # becomes boolean true, not string "yes"
      DEBUG: on               # becomes boolean true
      COUNTRY: NO             # becomes boolean false (Norway code!)

# GOOD (quote string values)
services:
  web:
    environment:
      FEATURE_FLAG: "yes"
      DEBUG: "on"
      COUNTRY: "NO"

Erreur 8 : Clés dupliquées

Message d'erreur : Souvent pas d'erreur — la seconde valeur écrase silencieusement la première.

# BAD (duplicate 'ports' key - second one silently wins)
services:
  web:
    image: nginx
    ports:
      - "80:80"
    environment:
      - NODE_ENV=production
    ports:                    # DUPLICATE! This replaces the first ports
      - "443:443"

# GOOD (combine under single key)
services:
  web:
    image: nginx
    ports:
      - "80:80"
      - "443:443"
    environment:
      - NODE_ENV=production

Erreur 9 : Chemins volumes

Message d'erreur :

services.web.volumes contains an invalid type

Problème : Chemins Windows avec backslashes posent problème sans guillemets.

# BAD (Windows paths without quotes)
services:
  web:
    volumes:
      - C:\Users\me\app:/app     # Backslashes cause issues

# GOOD (use forward slashes or quotes)
services:
  web:
    volumes:
      - "./app:/app"
      - "/home/user/data:/data"
      - "C:/Users/me/app:/app"      # Forward slashes on Windows

Erreur 10 : Ancres YAML mal utilisées

Message d'erreur :

yaml: unknown anchor 'common'

Problème : Référencer une ancre (*nom) avant de la définir (&nom).

# BAD (reference before definition)
services:
  web:
    <<: *common          # ERROR: 'common' not defined yet

x-common: &common
  restart: always

# GOOD (define anchor first, then reference)
x-common: &common
  restart: always
  logging:
    driver: json-file

services:
  web:
    <<: *common
    image: nginx
  api:
    <<: *common
    image: node:20

Checklist de validation rapide

Avant docker compose up, vérifiez :

1. Exécutez docker compose config pour valider la syntaxe
2. Vérifiez les tabulations: grep -P '\t' docker-compose.yml
3. Quotez tous les mappings de ports
4. Pas de clés dupliquées au même niveau
5. Quotez les valeurs avec caractères spéciaux
6. Indentation cohérente (2 espaces recommandés)

Validez votre YAML avec notre convertisseur JSON-YAML →

Formater la sortie JSON de "docker compose config" →