Undefined control sequence

! Undefined control sequence ist der erste LaTeX-Fehler, dem fast jede und jeder begegnet – und streng genommen gar kein LaTeX-Fehler: Reines TeX gibt genau diese drei Wörter aus, ganz ohne geladenes LaTeX. Control sequence ist TeX’ eigener Begriff für „Backslash plus Name“, und die Meldung sagt nur, dass dieser Name nicht im Wörterbuch steht. Zur meistgesuchten Fehlermeldung wird sie durch das, was danach passiert: TeX hält nicht an. Es verwirft den unbekannten Befehl stillschweigend, liest weiter und liefert am Ende ein PDF, in dem die Argumente des Befehls zu gewöhnlichem Fließtext geworden sind. Diese Seite behandelt die drei Ursachen, die fast alle Fälle abdecken – ein Tippfehler, ein nie geladenes Paket und ein Makro, das vor seiner Definition benutzt wurde –, und die Falle, dass die Zeilennummer im Log dort steht, wo TeX es bemerkt hat, nicht unbedingt dort, wo der Fehler sitzt.

Die Meldung lesen: der Umbruch in der Zeile zeigt den Übeltäter

Der Befehl am Ende der oberen der beiden Zeilen ist der undefinierte. Meldet TeX einen Fehler, teilt es die betroffene Zeile in das bereits Gelesene und das noch nicht Gelesene und stapelt beide Hälften übereinander. Gelesen wurde bis zu dem Moment, in dem die Sache schiefging – der Umbruch zeigt also unmittelbar auf den Übeltäter. Unten steht echte Log-Ausgabe zu \textbf, versehentlich als \textbnf getippt.

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

l.4 heißt Zeile 4. Tritt das Problem in einer Formel auf, kann über l.4 zusätzlich eine Zeile wie <recently read> \fra erscheinen, die den Befehl für sich allein nennt. So oder so ist der erste Schritt, im eigenen Quelltext nach diesem Befehlsnamen zu suchen. Stimmt die Schreibweise, geht es im nächsten Abschnitt weiter. Ein Tippfehler im Paketnamen führt übrigens zu einer ganz anderen Meldung: ! LaTeX Error: File und dahinter der Name der fehlenden .sty-Datei.

Nur drei Ursachen: Schreibweise, Pakete, Reihenfolge der Definition

In der Praxis laufen die Ursachen auf genau drei hinaus: ein Tippfehler, ein vergessenes Paket und ein Makro, das vor seiner Definition benutzt wird. Auch die Reihenfolge zählt – die Liste von oben nach unten abzuarbeiten ist am schnellsten, denn die Schreibweise zu prüfen dauert Sekunden, die Präambel zu prüfen einen Blick, und nur der Makrofall kostet wirklich Zeit.

• Ein Tippfehler – \fra statt \frac, \textbnf statt \textbf, \begni statt \begin. Befehlsnamen unterscheiden Groß- und Kleinschreibung, \Latex statt \LaTeX ist also ebenfalls undefiniert.
• Ein nie geladenes Paket – die Schreibweise stimmt, aber das Paket, das den Befehl definiert, wurde in der Präambel nie mit \usepackage geladen. Siehe die Tabelle im nächsten Abschnitt.
• Ein Makro vor seiner Definition – ein vergessenes \newcommand, eine Verwendung oberhalb der definierenden Zeile, oder eine Definition innerhalb von Klammern oder einer Umgebung, die außerhalb davon wieder verschwindet.

Welches Paket definiert den Befehl?

Die Tabelle unten ordnet den Befehlen, die aus diesem Grund am häufigsten undefiniert sind, das jeweils definierende Paket zu (mit \ifdefined unter TeX Live 2024 nachgeprüft). Die häufigste Verwechslung ist amsmath gegen amssymb. \lVert steckt in amsmath und nicht in amssymb; \mathbb und \therefore stecken in amssymb und nicht in amsmath. Ist ein Mathe-Befehl undefiniert, obwohl „das Paket doch geladen ist“, liegt es zuerst daran. Für alles, was nicht in der Tabelle steht, öffnet texdoc PACKAGE das Handbuch des Pakets.

Wenn \newcommand nicht greift: Reihenfolge und Gültigkeit

TeX liest von oben nach unten, und nur einmal – die Definition muss also vor der Verwendung stehen. Menschen betrachten eine Quelldatei als Ganzes; TeX liest Zeile für Zeile und trägt einen Namen erst in dem Moment ins Wörterbuch ein, in dem es das \newcommand erreicht. Ein in Zeile 200 definiertes Makro, in Zeile 40 verwendet, ist undefiniert. Die zweite Falle ist der Gültigkeitsbereich: Ein innerhalb von Klammern oder einer Umgebung definiertes Makro verschwindet an der schließenden Klammer. Beide Pannen entfallen, wenn die Definitionen in der Präambel stehen. Wie \newcommand selbst funktioniert – Argumente, Vorgabewerte, Unterschied zu \renewcommand –, behandelt die Seite „Makros definieren“.

\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}

Wenn die gemeldete Zeile nicht der Ort des Fehlers ist

Steht über l.NN eine Zeile mit ->, sitzt der Fehler im Makro, das dort genannt wird. l.NN ist nur die Stelle, an der TeX etwas bemerkt hat – also die Zeile, in der das Makro benutzt wurde. Die Definition kann Hunderte Zeilen entfernt liegen oder in einem Paket stecken. Im Beispiel unten ruft \mysq das Makro \mynorm auf, das \lVert verwendet, und amsmath wurde nie geladen. Die Log-Zeile \mynorm #1->\lVert ist der einzige Hinweis.

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

Auffällig ist, dass \mysq in diesem Log gar nicht vorkommt. LaTeX setzt \errorcontextlines auf -1 (Zeile 535 von latex.ltx), deshalb wird nur die innerste Ebene der Makro-Aufrufkette gezeigt. Wenn der Fehler in einem Paket steckt, reicht das nicht. Ein \errorcontextlines=999 in der Präambel und ein erneuter Lauf ergänzen die Zeile \mysq #1->\mynorm {#1}, und der ganze Aufrufweg wird sichtbar. Nach der Diagnose wieder entfernen – im Alltag liest sich ein ruhiges Log besser.

Das PDF entsteht trotzdem – und genau das ist gefährlich

Ein undefinierter Befehl hält den Satz nicht auf. TeX wirft genau diesen einen Befehl weg und setzt den Rest als gewöhnliche Zeichen. Wer graphicx vergisst und \includegraphics[width=3cm]{example-image} schreibt, bekommt nicht nur kein Bild, sondern ein PDF, in dem die Optionen und der Dateiname als Fließtext gedruckt stehen. Editoren und Build-Werkzeuge laufen standardmäßig mit -interaction=nonstopmode, der Lauf zieht also an den Fehlern vorbei und liefert eine Datei ab – genau so wird ein kaputtes PDF eingereicht. Bleibt auch nur ein undefinierter Befehl im Log, ist dem PDF nicht zu trauen.

% 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