エラーと警告を読むゾ

LaTeX Workshop では、エラーや警告のメッセージが一覧で表示される。そのため、ターミナルログや LOG ファイルを読む必要はない。

これをきちんと使いたい。

Recipe terminated with error

“Recipe terminated with error” で困っている人向けの節。

“Recipe terminated with error” は LaTeX のエラーメッセージではなく、「LaTeX Workshop がレシピを実行したが、エラーを含んで終了した」ことを知らせるメッセージである。そのため、LaTeX のエラーメッセージを確認する必要がある。

したがって、コンパイルしたときにポップアップが表示された際には、Ctrl+Shift+M (Shift+Cmd+M) を押下しよう。これによって開かれる PROBLEMS パネルにメッセージが記載されている。このメッセージの確認方法はこの節を参照。

もしも、この方法で解決できない場合にはそれぞれの節を参照。

エラーメッセージが表示されない場合 ^{[ ↓ ]}
“spawn xxxxx ENOENT” が表示される場合 ^{[ ↓ ]}

○ 正しくログを LaTeX Workshop に引き渡す

LaTeX はそもそもターミナルで利用するコマンドラインツールであり、LaTeX Workshop ではこれを簡便に実行するために tools と recipes が提供されている。ここで、tools には LaTeX のオプション引数を含めることが出来るが、必ず含めるべきものがいくつかある。これは LaTeX Workshop に正しくログを引き渡す要件として必要になる。

# The PROBLEMS Pane displays wrong messages - FAQ

LaTeX Workshop に正しくログを引き渡す要件として、LaTeX に 2 つのオプション引数を課す必要がある。

-file-line-error
-interaction=nonstopmode or -halt-on-error

オプション引数	説明
`-file-line-error`	メッセージスタイルを `file:line:error` に変更。 LaTeX Workshop はこのスタイルでないとエラーなどの該当箇所にジャンプ出来ない。^[↗]
`-interaction=nonstopmode`	LaTeX と対話せずに重大なエラー以外は適当に処理してエラーや警告としてターミナルログに出力する。この他のモードは LaTeX Workshop で利用しても意味がない： `errorstopmode` (default), `scrollmode`: エラーがある場合、ユーザーに入力を求めるため不向き `batchmode`: ターミナルログを生成しないので、LaTeX Workshop がエラーや警告を認識できない
`-halt-on-error`	初めのエラー箇所で処理を止める。以下の場合で有用：エラーを逐次確認したい場合エラーが大量に表示される場合無限ループが発生する場合

これを踏まえて基本的に、どの LaTeX を利用していても ~.tools の args には少なくとも次のようにしておくべきだろう。

  "latex-workshop.latex.tools": [
    {
      "name": "XXLaTeX",
      "command": "xxlatex",
      "args": [
        "-file-line-error",
        "-interaction=nonstopmode",
        "%DOC%"
      ],
    },
  ],

これに加えて、SyncTeX を利用して PDF と TeX ファイル間をジャンプしたい場合には、-synctex=1 を追加しておくと良い。

これらの引数は .latexmkrc 内で課していても良いだろう。（ちなみに、latexmk における -silent オプションは batchmode に相当するらしい。）

■ コンパイルが終了しない

小さいファイルであっても終了しないパターンは次の 2 つが考えられる。

nonstopmode になっていない（対話モードになっている）
latexmk などのビルドツールでファイルを監視している（e.g. latexmk では -pvc）

この手の問題があるかどうかを検証するのであれば、以下のような意図的にエラーが生じるファイルをコンパイルしてみると良い。問題なければ、コンパイルが終了し PROBLEMS パネルに Undefined control sequence. と表示される。

\documentclass{article}
\begin{document}
  Hello, \LaTex{}!!
  % 正しくは `\LaTeX{}'
\end{document}

しかしながら、十分な時間が経ってもコンパイルが終了しない場合もある。このときにはプロセスを強制的に終了する必要がある。コマンドパレットから次のコマンドを実行する。

> LaTeX Workshop: Kill latex compiler process

あるいは、キーボードショートカットで以下のように追加しておくと、簡単に実行を停止することが出来る。以下では Ctrl+Alt+K とした。

  {
    "key": "ctrl+alt+k",
    "command": "latex-workshop.kill",
    "when": "editorLangId == latex",
  },

macOS では key を Cmd+Alt+K とすると良いだろう。

  {
    "key": "cmd+alt+k",
    "command": "latex-workshop.kill",
    "when": "editorLangId == latex",
  },

macOS におけるキーバインドの設定での修飾子キーは Ctrl、Shift、Alt、Cmd の 4 つである。Option ではなく Alt であることに注意が必要。

# Accepted keys - Visual Studio Code Key Bindings

○ PROBLEMS パネルでログメッセージを確認する

# Catching errors and warnings - Compile

コンパイルした LaTeX にエラーが含まれる場合、PROBLEMS パネルにエラーや警告、Bad box が表示される。この PROBLEMS パネルは Ctrl+Shift+M (Shift+Cmd+M) で表示させることが出来る。

例として以下のような結果を得ることがある。（日本語化している場合、PROBLEMS パネルは「問題」と表記されている）

記号	メッセージの種類	意味
	エラー	PDF を出力できない致命的な問題
	警告	意図した出力となっていない可能性のある問題
	Bad box	指定された領域からはみ出している Understanding underfull and overfull box warnings - Overleaf

LaTeX のエラー関連は PROBLEMS パネルを確認すれば一覧で見ることが出来る。これに対応して左下のステータスバーに以下のメッセージが表示されている。

また、この PROBLEMS パネルのエラーメッセージをクリックするとエディタ上の該当箇所にジャンプすることが出来る。該当箇所には波線が引かれている。この波線にマウスポインタを合わせるとホバーでエラー内容を見ることも出来る。

LaTeX のエラーメッセージは以下のような一覧を見ることで、原因を特定することが出来る。

今回のテストファイル（折りたたみ）

\documentclass{jlreq}
\usepackage{amsmath}
\newcommand{\cmdname}[1]{\texttt{\textbackslash #1}}
\newcommand{\pkgname}[1]{\textsf{#1}}
\begin{document}

\begin{equation}
  \bm{V} \text{: \cmdname{bm} command is provided by \pkgname{bm} package. \cmdname{bm} command means vector and provides bold italic style.}
  \label{eqn:bm}
\end{equation}

Cross-reference \cmdname{label\{eqn:bm\}}:
\ref{eqn:bm}

\end{document}

○ ターミナルログを見る

ターミナルログは Ctrl+Shift+U (Shift+Cmd+U) から表示できる OUTPUT パネルの LaTeX Compiler に出力される。（ターミナルログと書いているが、OUTPUT パネルで見ているものはターミナルではないことに注意が必要）

これを見るには、コマンドパレットから以下を実行する。

> LaTeX Workshop: View LaTeX compiler logs

あるいは、キーボードショートカットで以下のように追加しておくと、簡単に LaTeX Compiler を開けることが出来る。

  {
    "key": "ctrl+shift+u",
    "command": "latex-workshop.compilerlog",
    "when": "workbench.panel.output.active && editorLangId == latex",
  },

macOS では key を Shift+Cmd+U とすると良いだろう。

  {
    "key": "shift+cmd+u",
    "command": "latex-workshop.compilerlog",
    "when": "workbench.panel.output.active && editorLangId == latex",
  },

○ ポップアップ

コンパイルに失敗するとポップアップで次のようなメッセージが表示されるが、これは LaTeX にとって本質的なメッセージではない。

❌ Recipe terminated with error.

これは単に「コンパイルに失敗しました」と言っているだけである。このメッセージをどのように読み解こうとしても LaTeX を正常にコンパイルすることは出来ない。

また、"latex-workshop.latex.autoBuild.cleanAndRetry.enabled": true にしている場合、次のようなポップアップを得ることもある。

⚠️ Recipe terminated with error. Retry building the project.

これは「コンパイルに失敗しました。再試行してください」と言っている。これも LaTeX のエラーメッセージにとっては本質的には意味がない。

LaTeX にとって意味のあるエラーメッセージは、PROBLEMS パネルや LOG ファイルを見る必要がある。

■ ENOENT

次のようなポップアップを受けることがある。

❌ Recipe terminated with fatal error: spawn xxxxx ENOENT.

ENOENT とは “Error NO ENTry” の略であり、xxxxx と言うコマンドがエントリーされていないことを示している。すなわち、このポップアップメッセージは「xxxxx というコマンドが見つからない」ことを意味している。（この状態ではもちろんターミナルからでも実行できない）

解決方法は「LaTeX 環境変数の設定」や「LaTeX パスを通す」で検索して解決してほしい。これは PC や環境によってかなり異なるため、ここでは詳細を示さない。これは LaTeX 固有の問題ではなく、PC でコマンドが使えるかどうかの問題である。
パスを通しましょう。

あるいは、settings.json からパスを指定することも出来る（折りたたみ）

コマンドのあるディレクトリを PATH で指定する。PATH の指定先は例なので、実際に利用できるものではありません。

  "latex-workshop.latex.tools": [
    {
        "name": "latexmk",
        "command": "latexmk",
        "args": [
          // ...
        ],
        "env": {
          "PATH": "/Library/TeX/texbin"
        }
    },
  ],

PATH は、which コマンドや where コマンドを利用することで探すことが出来る。

which latexmk

where latexmk

この方法では ~.tools のそれぞれに PATH を記載する必要があり、かなり面倒くさい。場合によっては、ターミナルから直接実行する必要がある場合もあるため、パスを通すことをオススメする。

パスが通っているか・インストールされているか確認する

ターミナル上で利用する LaTeX エンジンを実行する。このとき、--version オプションを付けて実行すると良い。

以下の例では xxlatex という仮のエンジンを実行している。

xxlatex --version

また、そもそもエンジンがインストールされているか確認しても良いだろう。

tlmgr info xxlatex

【確認例】latexmk のパスが通っているか・インストールされているか（折りたたみ）

Windows 機に TeX Live 2022 をインストールした状態で確認する。

latexmk のパスが通っているか確認する。

$ latexmk --version
Latexmk: Invoked as 'd:\texlive\2022\texmf-dist\scripts\latexmk\latexmk'
Latexmk, John Collins, 17 Mar. 2022. Version 4.77

latexmk が存在しない場合、存在しない旨のメッセージが返ってくる。この例では latexmk が存在するため、バージョン情報を見ることが出来ている。

latexmk がインストールされているか確認する。

$ tlmgr info latexmk
package:     latexmk
category:    Package
shortdesc:   Fully automated LaTeX document generation
longdesc:    Latexmk completely automates the process of generating a LaTeX document. Given the source files for a document, latexmk issues the appropriate sequence of commands to generate a .dvi, .ps, .pdf or hardcopy version of the document. An important feature is the "preview continuous mode", where the script watches all of the source files (primary file and included TeX and graphics files), and reruns LaTeX, etc., whenever a source file has changed. Thus a previewer can offer a display of the document's latest state.
installed:   Yes
revision:    62767
sizes:       doc: 1069k, run: 417k, bin: 5k
relocatable: No
cat-version: 4.77
cat-license: gpl2
cat-topics:  compilation
cat-related: latexn prv arara
cat-contact-home: http://personal.psu.edu/~jcc8/software/latexmk/
collection:  collection-binextra

installed: の項目を見ると Yes となっているため、インストールされていることが確認できる。No の場合にはインストールされていない。

もしもインストールされていない場合は、$ tlmgr install latexmk や $ tlmgr install collection-binextra を実行するとインストールすることが出来る。

PATH の確認（折りたたみ）

TeX Live の PATH を確認するには、次のように確認する。

Windows の場合。

echo %PATH%

Windows 以外の場合。

echo $PATH

これを実行した際に、パスが通っていれば texlive を含むパスが表示される。例として、持っている Windows PC でこれを実行すると、次のようなパスが表示された。

D:\texlive\2022\bin\win32

このようなパスが表示されない場合はパスが通っていない。通しましょう。

■ ポップアップの非表示

ある程度慣れてくると、これらのポップアップは邪魔になってくる。もちろん、きちんとステータスバーを見る必要があるが、非表示にしてしまっても問題ないだろう。これらのポップアップがなくとも、ステータスバー左下を確認すれば問題ない。

エラーや警告がない場合	エラーや警告がある場合の例

以下の設定をそれぞれ false に設定することでポップアップを抑制することが出来る。

記号	設定	デフォルト値
	`latex-workshop.message.error.show`	`true`
	`latex-workshop.message.warning.show`	`true`
	`latex-workshop.message.information.show`	`false`

コンパイル以外で表示されるポップアップもあるため、注意する必要がある。

○ ログファイルを削除しない

latex-workshop.latex.autoClean.run の設定や Ctrl+Alt+C (Cmd+Alt+C) を実行すると中間生成ファイルを削除することが出来る。

しかしながら、デフォルトでは削除する中間生成ファイルの中に "*.log" が含まれるため、これも削除されてしまう。これではコンパイルが失敗したときのエラー原因を特定しづらくなる場合があるため、"*.log" を外しておくと良いだろう。

  "latex-workshop.latex.clean.fileTypes": [
    "*.aux",
    "*.bbl",
    // "*.blg", // BibTeX のログファイル
    "*.idx", "*.ind", "*.lof", "*.lot", "*.out", "*.toc", "*.acn", "*.acr", "*.alg", "*.glg", "*.glo", "*.gls", "*.fls",
    // "*.log", // LaTeX のログファイル
    "*.fdb_latexmk", "*.snm", "*.synctex(busy)", "*.synctex.gz(busy)", "*.nav"
  ]

○ 特定の警告を非表示にする

ここでの非表示とは、ターミナルログから PROBLEMS パネルに警告メッセージを引き渡さないことを指す。これに伴って、エディタ内の波線も引かれなくなる。
警告そのものが発行されなくなるわけではない。

LaTeX のコンパイルのうち、特定の警告に関して気にしなくても問題ない場合がある。

LaTeX Workshop では次のような設定から PROBLEMS パネルに特定の警告を拾わないようにすることが出来る。これらの設定は正規表現で指定することが出来る。

設定	説明
`latex-workshop.message.latexlog.exclude`	LaTeX のメッセージを抑制する
`latex-workshop.message.bibtexlog.exclude`	BibTeX のメッセージを抑制する

ここで指定する警告メッセージは、ターミナルログ行頭の LaTeX Font Warning: などの有無はどちらでも良いらしい。

！注意

さまざまな警告に関して非表示にしておいても良いが、自分が把握できていない警告を非表示にしておくと後々でかなり面倒なことになりかねないので注意が必要。（ターミナルログ等を見る癖のある人であれば問題ないが…）

また、稀に次のような設定を見かけるが、すべてのメッセージを非表示にしているのであまりオススメはしない。

  "latex-workshop.message.latexlog.exclude":[
    "(.*)"
  ],

■ 具体例 1

フォントに関する警告に次のようなものが出てくる場合がある。

LaTeX Font Warning: Font shape `JY1/mc/m/it' undefined

これは、「JY1/mc/m/it（和文フォントにおける斜体）が未定義だぞ」という警告である。LaTeX ではこれの後に未定義のフォントを何かで代用した旨が表示されることになる。

# “LaTeX Font Warning: Font shape `JY1/mc/m/it' undefined” といった警告が出る - よくある質問 - TeX Wiki

この警告は、適当にプリアンブルで設定をしておけば表示されないものの、少々煩雑であり、コンパイルに失敗するわけではない。そのため、非表示にしておいても良いだろう。

この警告を非表示にする場合には、次のように設定を課せば良い。

  "latex-workshop.message.latexlog.exclude": [
    "(Font shape `(JY1|JT1|JY2|JT2)(/.*)(sl|it|sc)'.*|Some font shapes were not available.*)",
  ],

# 日本語文書特有の LaTeX Font Warning を警告表示に含めないようにする - Visual Studio Code/LaTeX - TeX Wiki

■ 具体例 2

相互参照についての警告は次のようなものがある。

LaTeX Warning: Reference `labelName' on page 3 undefined on input line 15.

LaTeX Warning: Label(s) may have changed. Rerun to get cross-references right.

LaTeX Warning: There were undefined references.

相互参照の問題が解決していない場合、どれも表示される。これを非表示に構成したい場合には次のようにすれば良いだろう。

  "latex-workshop.message.latexlog.exclude": [
    "Reference `.+' on page \\d+ undefined on input line \\d+\\.",
    "Label\\(s\\) may have changed\\. Rerun to get cross-references right\\.",
    "There were undefined references\\.",
  ],

latexmk でコンパイルする場合には元から表示されない上、場合によってはこれがないと複数回のコンパイルを忘れてしまう場合も無きにしも非ずなので注意してほしい。

参考

公式 Wiki
- Compile
- # The PROBLEMS Pane displays wrong messages - FAQ

余談

LaTeX のエラーメッセージは分かりづらいという言説はよくあるが、“Recipe terminated with error” は LaTeX のエラーメッセージではない。

この他にも、ChkTeX や Lacheck を利用したり textlint を利用する際にもエラーや警告が PROBLEMS パネルに出力される。

追記

2022/07/12: キーバインドの表示を macOS にも対応
2022/08/12: 軽微修正
2022/08/20: パスやインストールの確認方法について追記
2022/10/28: コードブロックのハイライトを追加