LaTeX のエラーを解決するのは初心者であればあるほど難しいと感じられるようだ．
具体的な解決法ではなく，ワークフローとしてどのような手段を利用すればエラーを解決出来るかを考えてみた．
Outline TOC
本記事は記事内で何かしらのエラーを解決するものではなく，エラーを解決する道筋を示すためのものである．
解決の道筋を簡単に示しておきたい．
mermaid ソースコード (折りたたみ)
graph TD
%% Usage Guide
userOperation([ユーザ操作])
tool[/ツール/]
scriptResult{{実行結果}}
%% Graph
edit([TeX ドキュメントを編集])
staticAnalysis[/静的解析/]
syntaxError{{エラーを検出}}
syntaxNoError{{エラーなし}}
errorEditAnalysis([エラーを修正])
compile[\LaTeX タイプセット/]
interactiveMode[/対話モード/]
nonInteractiveMode[/非対話モード/]
errorInteractive{{エラーを検出}}
userInput([入力])
continueInteractive{{継続}}
errorEditCompile([エラーを修正])
finishInteractive{{終了}}
clearIntermediateFile([中間ファイルを削除])
successWithError{{エラーを含む終了}}
emergencyStop{{緊急停止}}
interactionModeSuccess{{タイプセット終了}}
nonInteractionModeSuccess{{タイプセット終了}}
Success((PDF 完成!!))
%%
subgraph Typeset Process
subgraph Usage Guide
userOperation;
tool;
scriptResult;
end
edit ==> staticAnalysis;
subgraph Static Analysis
staticAnalysis --> syntaxError;
staticAnalysis --> syntaxNoError;
end
syntaxError --> errorEditAnalysis;
errorEditAnalysis --> staticAnalysis;
subgraph Compile
syntaxNoError ==> compile;
%%
%% Switch Compile type
compile ==errorstopmode==> interactiveMode;
compile ==nonstopmode==> nonInteractiveMode;
%%
%% nonInteraction mode
subgraph non-Interactive ... ... ... ... ... ...
nonInteractiveMode ---> interactionModeSuccess;
nonInteractiveMode ---> successWithError;
nonInteractiveMode ---> emergencyStop;
end
%%
%% Interactive mode
subgraph Interactive ... ... ... ... ... ...
interactiveMode --> errorInteractive;
interactiveMode ----> nonInteractionModeSuccess;
errorInteractive --> userInput;
userInput --> finishInteractive;
userInput --> continueInteractive;
continueInteractive --> errorInteractive;
end
end
%%
%% Success
nonInteractionModeSuccess --> Success;
interactionModeSuccess --> Success;
%%
%% Error correction
finishInteractive --> errorEditCompile;
emergencyStop --> errorEditCompile;
successWithError --> errorEditCompile;
errorEditCompile --> clearIntermediateFile;
clearIntermediateFile ----> compile;
%%
end
LaTeX はターミナル# から実行するコマンドラインツールである．そのため，以下で見るような引数によってエラーの表示に関して設定することが出来る．
LaTeX コマンドのオプション引数は数多くあるが，エラーに関するオプション引数は以下のようなものがある．(先頭のハイフンが2つの場合もある)
これらはどのエンジンでも同じ挙動となっているようだ．
| Option argument | Description |
|---|---|
-file-line-error |
メッセージスタイルをfile:line:error に変更 |
-interaction=STRING |
対話モード．4つの異なる設定がある |
-halt-on-error |
初めのエラーの箇所で処理を止める |
-interaction=STRING の詳細は以下のようになっている．STRING にerrorstopmode に置き換えれば良い．
STRING |
Terminal Output | Patch Errors | Emergency Stop | User Input | Remarks |
|---|---|---|---|---|---|
errorstopmode (default) |
✓ | - | - | ✓ | エラー発生時にユーザの入力を要求 |
scrollmode |
✓ | ✓ | - | ✓ | 不足しているファイルをユーザに要求 |
nonstopmode |
✓ | ✓ | ✓ | - | - |
batchmode |
- | ✓ | ✓ | - | - |
表の各項目は以下の通りである．
| Item | Description |
|---|---|
| Terminal Output | ターミナルに出力する |
| Patch Errors | エラーをパッチで回避する |
| Emergency Stop | 重大なエラーの際に緊急停止する |
| User Input | ユーザに入力を求める |
エディタ内でLaTeX を実行する (折りたたみ)
LaTeX は基本的に対話モードで実行される． そのため，エラーに当たるたびにユーザに何らかの入力を求める．
したがって，何かしらのエディタを利用してLaTeX を作成，コマンドの実行をする場合には以下のような理由から設定は一意に決定されることが多いだろう．
- エディタがLaTeX との対話に対応していない
- エラーや警告，Badbox を集積して一覧表示させる機能がある
- 一つ一つエラーに当たるのは面倒くさい．ドキュメントが大型になればなおさらである．
また，-file-line-error を有効にしておけばエディタによってソースファイルにジャンプさせてくれるようになる．
これらの理由からエディタ内で利用する場合には以下のようにしておくと良いだろう．
latex -interaction=nonstopmode -file-line-error
このときbatchmode にしてしまうとエディタにエラーメッセージを伝達出来なくなってしまうため注意が必要である．
対話術 (折りたたみ)
対話モードの場合，ユーザが発言できる言葉は以下の通りである．
| Return Word | Description |
|---|---|
h |
エラーの詳細を見ることが出来る |
i |
エラー部分を任意に置き換えることが出来る |
s |
scrollmode に切り替え |
r |
nonstopmode に切り替え |
q |
batchmode に切り替え |
e |
編集画面を開く (対応していないエンジンもある) |
x |
終了 |
もしも対話モードで編集する場合にはh からエラーの詳細を見ることも出来るだろう．
ターミナル内やlog ファイルに記載されるメッセージには以下のような種類がある．
| Message Type | Description |
|---|---|
! から始まるメッセージ |
TeX が出すエラーメッセージ |
! LaTeX Error |
LaTeX が出すエラーメッセージ |
LaTeX Warning, LaTeX Font Warning |
警告メッセージ |
もしもLaTeX のタイプセットが途中で止まったり，ターミナルやlog ファイルに上のようなメッセージが記載されていた場合には注意深く見る必要があるだろう．
エラーが生じるパターンは大きく分けて以下のような原因が挙げられる．
以下では，すべてのエラーメッセージについて網羅しているわけではないが，いくつかの頻出エラーメッセージについての解決策を示している．
エラーメッセージの一覧については以下を参照すれば良いだろう．
未定義のコマンドや環境へのエラーメッセージはタイプミスへのエラーメッセージだと思ってもほとんど問題ない場合が多い．
これらの原因は以下のようなものが挙げられる．
- 環境/コマンドを提供しているパッケージを読み込んでいない
- タイプミス
パッケージから提供されているコマンドは\usepackage しない限りには利用できません．一番に確認してください．
- 未定義のコマンドがある
! Undefined control sequence
- 未定義の環境がある
! Environment <misspell_env_name> undefined
\beginと\endの環境名が異なる
! \begin{<env_x>} on input line <line_no> ended by \end{<env_y>}
これは事前に知ることが出来る．
Go to → # 静的解析
} や\end{<env_name>} が見つからない場合，以下のようなエラーメッセージが表示される．
}が見つからない
! File ended while scanning use of <command>
コマンドの引数の閉じ括弧} はShift+] を押下する必要があり，よく角括弧] とタイプミスしやすい．
\env{<env_name>}が見つからない
! Paragraph ended before \<env_name> was complete.
これは事前に知ることが出来る．
Go to → # 静的解析
警告内にまれに<command> に@ を含むコマンドを示している場合がある．
! File ended while scanning use of <command_include_@>
この@ を含むコマンドはLaTeX ユーザが利用するためのコマンドではなく，開発側が使用するコマンドとなっていることが多い．
したがって，編集している.tex ドキュメント内に修正すべき箇所は存在しない可能性がある． 中間ファイルを削除すると解決する場合が多い．
Go to → # 中間ファイルの削除
コマンドの使い方のミスはパッケージガイドを参照して確認することが最も有効だと思われる．
Go to → # 文書クラスやパッケージのガイドドキュメントを開く
パッケージであればある程度その違いを理解して利用することが出来ると思われるが，文書クラスもそれぞれ勝手が異なることに注意が必要である．
たとえば，jsclasses とBXjsclas とjlreq ではまったく勝手が異なる．
パッケージの衝突も往々にして起こりやすい．たとえば，以下のようなエラーメッセージを受け取ることになる． (当然ながらユーザが定義したコマンドがすでに定義されている場合にも同様のエラーメッセージを得る)
! LaTeX Error: Command <some_command> already defined.
これは複数のパッケージで同一のコマンドを定義しているためにエラーとなっている．
このようなパッケージの衝突はパッケージの読み込み順序を変更することで解消される場合がままある．読み込み順序とは\usepackage する順番のことである．
読み込み順序に関してもパッケージガイドを確認すると良いだろう．
Go to → # 文書クラスやパッケージのガイドドキュメントの閲覧
参考として，以下のような記事を読んでおくのも良いだろう．
また，パッケージの衝突はパッケージのバージョンに依存して発生している場合もある．適宜tlmgr で更新してみることで解消されることもあるだろう．
エディタの設定に関することはエディタの公式ページを参照することが最優先だろう． エディタの設定を紹介する記事は数多にあるが，公式ページを参照することに勝るものはないと思われる．
TeXstudio であれば以下のようなページ．
LaTeX Workshop on VSCode であれば以下のようなページ．
他エディタは各自検索のこと．
上で示したような対応をしてもエラーを解消できない場合，バグを疑っても良いかもしれない．
まずは最新版に更新しよう．
tlmgr で更新することでバグが修正されている場合もある．
それでもバグが生じてしまう場合は，GitHub 等で開発されているものであればIssue を挙げると良いだろう．
タイプセットする前に静的解析してエラー部分を事前に把握しておくと良いだろう．
静的解析では環境やコマンドのタイプミスや未定義かどうかは判定できない． あくまでLaTeX 構文が正しいかどうかのみを判定することが出来る．
静的解析ツールには以下のようなものがある．
- ChkTeX
- LaCheck
使い方は簡単である．ターミナルで以下のようにすれば良い．
$ chktex hoge.tex
$ lacheck hoge.tex
ChkTeX ではいくつかのエラー警告を取り除くことが出来る．.chktexrc ファイルを作成すれば良いだろう．
エディタで静的解析 (折りたたみ)
Atom やVSCode ではエディタ内にChkTeX の解析結果を取り込むことが出来る．
また，VSCode であれば以下のような拡張機能もある． 様々な言語の文法とLaTeX 構文の解析を行うことが出来る．
valentjn.vscode-ltex - VSCode Marketplace
TeXstudio ではLanguageTool (Java を使用) を利用して文法チェックを行うことは出来るが，LaTeX の構文解析は出来ないようだ．
エラーを取り除くために中間ファイル# を削除することがある．
これらのファイルはLaTeX が相互参照などを処理するために作成したファイルなので，改めてコマンドを実行すればいくらでも作成することが出来る．躊躇なく削除してしまおう． 簡単に言えば，自分で作成したファイル以外はすべて削除して問題ない．
多くのエディタでは中間ファイル(あるいは補助ファイル) の削除の項目やキーボードショートカットが用意されているはずである． これを利用すれば簡単に削除することが出来る．
文書クラスやパッケージにはそれぞれガイドとなるドキュメントが与えられている． これを参照したい．
以下で紹介している際に与えている<package_name> がすべての\usepackage で使用する名前ではないということにも注意したい．
ローカルにTeX 環境を構築している場合にはtexdoc を利用して，パッケージガイドを呼び出すことが出来る．
$ texdoc <package_name>
基本的には英語ドキュメントが呼び出されるが，(u)pLaTeX 向け(日本語向け)に作成された文書クラスやパッケージであれば<package_name>-ja などとすると日本語ドキュメントを呼び出すことも出来る．
英語ドキュメントと同じディレクトリに入っているので，英語ドキュメントから日本語ドキュメントを探すことも出来るだろう．
インターネット上ではCTAN から検索することで同様のドキュメントを参照することが出来る． Google 等で以下のような検索をすればPDF ドキュメントを得ることが出来るだろう．
🔍 ctan <package_name>
あるいは，以下のURL を用いて<package_name> に適宜入れれば直接アクセスできるだろう．パッケージによってはアクセスできない場合もあるので注意が必要になる．
https://www.ctan.org/pkg/<package_name>
エラーメッセージが現れる場合とは異なり，警告メッセージが現れる場合には処理が中断せずに一応続行してしまうため，ともすると警告メッセージは軽視されがちです． しかし，警告メッセージが現れた場合には “処理結果が意図したものとは異なるものになっている可能性”があるため，エラーメッセージと同等に注意を払うべきメッセージもあります．
警告メッセージについては以下を参照すると良いだろう．
フォント周りの警告は少し解決が面倒な印象がある．
次のような警告はよく見ることになるだろう． 相互参照の問題が解決していないことを示している． LaTeX コマンドを繰り返し実行すれば解消される．
LaTeX Warning: Label(s) may have changed. Rerun to get cross-references right.
LaTeX でタイプセットしていると途中で止まってしまうことがある．この場合，さまざまなコミュニティやSNS で質問することがあるが，これらの場で質問するときの必要事項を挙げておきたい．
- OS (Windows, macOS, Linux など)
- ディストリビューション (TeX Live20** など)
- 実行コマンド (引数も必要な場合がある)
- エラーを再現する最小コード
- LOG ファイル (エラーメッセージを抽出しても良い)
単に問題を総投げしても解決できない場合が多分にある． 詳細は以下の記事に詳しい．
回答者はエラーの解決方法を与えることが出来る可能性があるが，エラーの原因を推察することは難しい．そのため，エラーの原因は質問者がある程度特定しておく必要があると思われる．
この意味でも「エラーを再現する最小コード」を作成することは非常に重要な作業だと思われる．
(本当は少し異なる気がするが)「エラーを再現する最小コード」は「エラーを起こさない部分が省かれたコード」とも読み替えることが出来ると思われる．
数百行のドキュメントをそのまま質問として投げると読む側もしんどい．誰も答えない可能性が高くなるだけだろう．
また，あまり気にしていない場合もあるが，LaTeX の文書クラスやパッケージも適宜更新されている．
バージョンによって生じているエラーの場合もある．
質問する際にこれらのバージョン情報まで挙げる必要はないかもしれないが，更新するとエラーが治ることや，更新によってエラーが生じることなどもある．どうしてもエラーの原因が特定できない場合にはこれを気にしても良いだろう．
LaTeX で質問する場所で代表的なところはTeX Forum になるだろう．ただし，このサイトも今年度限りになる可能性がある．
cf. QA: 本サイトの今後
あるいは，プログラミング全般に関するQA は以下のようなサイトを利用すると良いだろう．
英語版のStack Overflow では以下のような記事を一読しておくと質問しやすいと思われる．
cf. Stack Overflowの使い方 - Qiita
もちろんQiita でもQA することが出来るが，サイトの文化的に知識の記録と共有を目的としたユーザが多く，質問にはあまり期待しない方が良いと思われる．
LaTeX で使用するファイルは大きく分けて3種類ある．
| File Type | Extension |
|---|---|
| ソースファイル | .tex, .bib, .cls, .sty ...etc |
| 中間ファイル | .aux, .toc, .out, .bbl, .log ...etc |
| 最終生成ファイル | .pdf, .dvi, .synctex.gz ...etc |
ソースファイルの内，.cls や.sty はTeX を構築した際に勝手に入っているので特に気にする必要はない．
用意すべきファイルは.tex (とBibTeX を利用する場合は.bib ) である．
最終生成ファイルはLaTeX ユーザがもっとも欲しいファイルである．(.dvi はよっぽど要らないという話は多分にある)
中間ファイルは相互参照や目次索引などが記載されたファイルになる．LaTeX は複数回繰り返してコマンドを実行することによって，中間ファイルを処理するようになる．
コマンド実行1回目で中間ファイルを作成し，2回目以降で中間ファイルを含めて処理する．
ターミナルとは何かを説明すると結局何者なのか分からなくなるので，具体例のみを示しておきたい．
OS ごとに異なるさまざまなターミナルがある．
| OS | Terminal |
|---|---|
| Windows | コマンドプロンプト，PowerShell ...etc |
| macOS | ターミナル，iTerm ...etc |
| Linux | bash，Konsole ...etc |
操作はCUI でコマンドを打ち込む．
例 :
$ latex hoge.tex
ここで$ はコマンドの実行を意味している．また，このターミナルを開いているディレクトリはhoge.tex が格納されているディレクトリとなっている．