Undefined control sequence

! Undefined control sequence est la première erreur LaTeX que presque tout le monde rencontre, et à strictement parler ce n’est même pas une erreur de LaTeX : le TeX brut affiche exactement ces trois mots sans qu’aucun LaTeX ne soit chargé. Control sequence est le terme propre à TeX pour « une barre oblique inverse suivie d’un nom », et le message dit seulement que ce nom ne figure pas dans son dictionnaire. Ce qui en fait l’erreur la plus recherchée, c’est la suite : TeX ne s’arrête pas. Il jette silencieusement la commande inconnue, poursuit sa lecture et vous remet un PDF où les arguments de la commande sont devenus du texte courant. Cette page traite les trois causes qui couvrent presque tous les cas — une faute de frappe, un package jamais chargé, une macro employée avant d’exister — et le piège du numéro de ligne, qui indique où TeX s’en est aperçu, pas toujours où se trouve la faute.

Lire le message : la coupure de la ligne désigne le coupable

La commande à la fin de la première des deux lignes est celle qui n’est pas définie. Lorsque TeX signale une erreur, il coupe la ligne fautive entre ce qu’il a déjà lu et ce qu’il n’a pas encore lu, et empile les deux moitiés. Il s’est arrêté de lire à l’instant même où le problème est survenu : la coupure désigne donc directement le coupable. Voici une sortie de log réelle pour \textbf saisi par erreur \textbnf.

! Undefined control sequence.
l.4 This is \textbnf
                    {bold} text.

l.4 désigne la ligne 4. Si l’incident survient dans une formule, une ligne comme <recently read> \fra peut s’ajouter au-dessus de l.4 et nommer la commande à elle seule. Dans tous les cas, le premier réflexe est de chercher ce nom de commande dans vos sources. Si l’orthographe est bonne, passez à la section suivante. À noter : se tromper dans le nom du package produit une tout autre erreur, ! LaTeX Error: File suivi du nom du .sty introuvable.

Trois causes seulement : orthographe, package, ordre de définition

En pratique, les causes se ramènent à trois : une faute de frappe, un package oublié et une macro employée avant sa définition. L’ordre compte aussi : parcourir la liste de haut en bas est le plus rapide, car vérifier l’orthographe prend quelques secondes, vérifier le préambule un coup d’œil, et seul le cas de la macro demande un vrai travail.

• Une faute de frappe — \fra pour \frac, \textbnf pour \textbf, \begni pour \begin. Les noms de commandes distinguent les majuscules : \Latex au lieu de \LaTeX n’est pas défini non plus.
• Un package jamais chargé — l’orthographe est bonne, mais le package qui définit la commande n’a jamais été passé à \usepackage dans le préambule. Voir le tableau de la section suivante.
• Une macro employée avant sa définition — un \newcommand oublié, un emploi au-dessus de la ligne qui la définit, ou une définition placée dans des accolades ou un environnement, donc effacée en dehors.

Quel package définit la commande ?

Le tableau ci-dessous associe aux commandes le plus souvent indéfinies pour cette raison le package qui les définit (vérifié avec \ifdefined sur TeX Live 2024). La confusion la plus fréquente oppose amsmath à amssymb. \lVert se trouve dans amsmath et pas dans amssymb ; \mathbb et \therefore se trouvent dans amssymb et pas dans amsmath. Si une commande mathématique reste indéfinie alors que « le package est chargé », commencez par là. Pour ce qui ne figure pas dans le tableau, texdoc PACKAGE ouvre le manuel du package.

Le \newcommand qui n’a pas pris : ordre et portée

TeX lit de haut en bas, une seule fois : la définition doit donc précéder l’emploi. L’œil humain embrasse un fichier source d’un coup ; TeX le lit ligne à ligne et n’inscrit un nom dans son dictionnaire qu’au moment où il atteint le \newcommand. Une macro définie ligne 200 et employée ligne 40 est indéfinie. L’autre piège est la portée : une macro définie entre accolades ou dans un environnement s’efface à l’accolade fermante. Ces deux accidents disparaissent si les définitions vivent dans le préambule. Le fonctionnement de \newcommand lui-même — arguments, valeurs par défaut, différence avec \renewcommand — relève de la page « Définir des macros ».

\documentclass{article}
\begin{document}
% too early: \R is not in the dictionary yet
$\R$
\newcommand{\R}{\mathbb{R}}

% scoped: \tmp dies at the closing brace
{\newcommand{\tmp}{scoped}\tmp}
\tmp
\end{document}

Quand la ligne signalée n’est pas celle de la faute

Si une ligne contenant -> apparaît au-dessus de l.NN, la faute se trouve dans la macro qui y est nommée. l.NN n’indique que l’endroit où TeX s’en est aperçu, c’est-à-dire la ligne où la macro a été employée. La définition, elle, peut se trouver des centaines de lignes plus loin, voire dans un package. Ci-dessous, \mysq appelle \mynorm, qui utilise \lVert, et amsmath n’a jamais été chargé. La ligne \mynorm #1->\lVert du log est le seul indice.

! Undefined control sequence.
\mynorm #1->\lVert
                   #1 \rVert
l.5 The value $\mysq{x}
                       $ is here.

Remarquez que \mysq n’apparaît nulle part dans ce log. LaTeX fixe \errorcontextlines à -1 (ligne 535 de latex.ltx), si bien que seul le niveau le plus interne de la chaîne d’appels est affiché. C’est insuffisant quand la panne se produit dans un package. Placez \errorcontextlines=999 dans le préambule et recompilez : la ligne \mysq #1->\mynorm {#1} s’ajoute et tout le chemin d’appel devient lisible. Retirez-la une fois le diagnostic posé — au quotidien, un log discret se lit mieux.

Le PDF est quand même produit, et c’est là le vrai danger

Une commande non définie n’interrompt pas la composition. TeX jette cette seule commande et compose le reste en caractères ordinaires. Oubliez graphicx et écrivez \includegraphics[width=3cm]{example-image} : vous n’obtenez pas seulement une image manquante, mais un PDF où les options et le nom du fichier sont imprimés dans le texte. Éditeurs et outils de compilation tournent par défaut avec -interaction=nonstopmode ; la compilation passe donc outre les erreurs et livre un fichier — c’est exactement ainsi qu’un PDF défectueux se retrouve rendu. S’il reste ne serait-ce qu’une commande non définie dans le log, ne faites pas confiance au PDF.

% graphicx was never loaded
\includegraphics[width=3cm]{example-image}

% the run still succeeds, and this is what lands on the page:
%   [width=3cm]example-image