Corriger l'erreur Mermaid « got 'PS' » (parenthèses dans les labels)

Si votre diagramme Mermaid échoue avec Parse error ... Expecting 'SQE', 'PE', ... got 'PS', la cause est presque toujours une parenthèse dans un label de nœud. Mermaid se sert de ( et ) pour définir la forme des nœuds — A(texte) est une boîte arrondie — donc quand il tombe sur un ( inattendu à l'intérieur d'un label, il signale le token PS (paren-start) qu'il n'attendait pas. La solution : mettre le label entre guillemets. Voici le pourquoi et le comment.

Où ça apparaît

Mermaid rend des diagrammes dans le Markdown de GitHub et GitLab, Notion, Obsidian et la plupart des générateurs de docs. Le parser est le même partout : un label avec une parenthèse échoue de façon identique dans un README ou dans l'éditeur en ligne. Le correctif ci-dessous est portable.

Pourquoi l'erreur arrive

Dans un flowchart, les caractères autour du texte choisissent la forme du nœud :

A[Carré]
B(Arrondi)
C((Cercle))
D{Losange}

Le parser lit ( comme « ici commence un label de forme arrondie ». Un label comme :

A[Déploiement (production)]

le perd : il est déjà dans [...], rencontre (, et lève Expecting ... got 'PS'. Même chose avec un ( dans un label d'arête ou partout où la grammaire n'attendait pas de délimiteur de forme.

La solution : mettre le label entre guillemets

Entourez le texte de guillemets doubles. Tout ce qui est entre guillemets est traité comme du texte littéral, parenthèses comprises :

A["Déploiement (production)"]

Ce seul changement résout la grande majorité des erreurs « got 'PS' ». Ça marche pour toutes les formes :

A["Build (CI)"]
B("Release (taguée)")
C{"Validé ? (manuel)"}

Quand les guillemets ne suffisent pas : les entités HTML

Les guillemets règlent les parenthèses. Si vous avez besoin de caractères que Mermaid traite spécialement même entre guillemets — ou sur un moteur de rendu ancien qui bloque dessus — utilisez les entités HTML numériques dans le label :

A["Déploiement #40;production#41;"]

#40; vaut ( et #41; vaut ). D'autres utiles : #35; pour #, #59; pour ;, et #quot; pour un guillemet double littéral. Les entités sont la sortie de secours quand les guillemets seuls cassent encore.

Avant / après

Cassé :

flowchart TD
  A[Début] --> B[Tests (unitaires)]
  B --> C[Déploiement (prod)]

Corrigé :

flowchart TD
  A[Début] --> B["Tests (unitaires)"]
  B --> C["Déploiement (prod)"]

Une checklist pour « got 'PS' » et ses cousins

La même famille d'erreur apparaît avec d'autres tokens inattendus (got 'PE', got 'STR'). La cause racine est en général l'une de celles-ci :

Parenthèses dans un label → mettre le label entre guillemets.
Crochets, accolades ou barres ([, ], {, }, |) dans un label → guillemets ; entités si ça casse encore.
Deux-points ou point-virgule là où Mermaid attendait un mot-clé → guillemets ou entité.
Un guillemet parasite dans un label déjà entre guillemets → l'encoder en #quot;.

Traitez label par label. Guillemets d'abord ; entités seulement si un caractère précis survit aux guillemets.

Pourquoi ça pique si souvent

Les labels décrivent des systèmes réels, et les systèmes réels ont des noms comme « Service auth (v2) » ou « Retry (max 3) ». Les parenthèses sont naturelles en français et illégales en texte brut de label Mermaid. Prendre l'habitude de mettre entre guillemets tout label contenant de la ponctuation vous évite de re-déboguer la même erreur à chaque nouveau nœud.

Sauts de ligne et autres balises dans les labels

Une fois le label entre guillemets, vous pouvez y insérer un saut de ligne avec la balise HTML <br> :

A["Déploiement en prod<br>(validation manuelle)"]

Quelques balises HTML sont autorisées dans les labels entre guillemets, mais un < ou un > employé comme texte brut peut déclencher sa propre erreur. Si vous avez besoin de chevrons littéraux, encodez-les en #lt; et #gt;, comme les parenthèses.

Lisez le numéro de ligne, puis bissectez

L'erreur Mermaid indique en général la ligne et le token qui coince — commencez par là, pas par le haut du diagramme. Si le message reste vague ou que le diagramme est gros, commentez (avec %%) ou supprimez la moitié des nœuds, re-rendez, et voyez si l'erreur se déplace. Deux ou trois passes suffisent à isoler le label fautif bien plus vite qu'en fixant tout le graphe.

Tester le correctif vite

Le plus rapide pour valider un correctif, c'est l'éditeur en ligne Mermaid sur mermaid.live : collez le diagramme et il se re-rend à chaque frappe, en affichant l'erreur et sa ligne. Corrigez le label, voyez l'erreur disparaître, puis recopiez la source qui marche dans votre README ou vos docs — bien plus rapide que committer et attendre que GitHub re-rende juste pour savoir si la parenthèse passe.

Et ensuite

Si vous générez vos diagrammes avec un assistant IA, ajoutez une consigne d'une ligne : toujours mettre entre guillemets les labels qui contiennent de la ponctuation. Ça supprime complètement ce mode d'échec. Pour des assistants qui encodent ce genre de conventions, parcourez le catalogue de skills ou la catégorie développement. Et si vous tenez un pense-bête de correctifs comme celui-ci, notre blog en rassemble d'autres.