Quarto 1.10.18でPDFが生成されない、処理が止まる、または字体や文献が欠ける場合は、症状ごとに原因を分けて確認します。
Quartoを先に再インストールせず、ログを保存して最小文書を試し、文書解析、コード実行、PDFエンジン、字体依存を順に切り分けてください。環境を安定して再現できない場合は、機密情報を除いた同一プロジェクトを隔離したmacOS環境で検証します。レンダリング成功だけでは、論文の内容や研究結果の正しさは確認できません。
MacでQuartoを使って論文やレポートを作成し、PDF出力の原因を特定したい大学院生・研究者向けです。
Quartoプロジェクトを保守する方や、大学のmacOS環境を支援する技術担当者にも役立つ手順をまとめています。
01 Quarto 1.10.18 Mac PDF出力失敗の初動
まず、失敗した状態を後から再現できる情報を残します。ログを取らずに環境を更新したり、設定をまとめて変更したりすると、原因を示す手掛かりが失われます。
- [ ] 実行したコマンドと、実行したディレクトリを記録する
- [ ] ターミナルの出力を、エラーの前後も含めて保存する
- [ ] Quartoのバージョンと診断結果を記録する
- [ ] 失敗した文書とプロジェクト設定のコピーを残す
- [ ] 個人情報や研究データを含まない最小文書で再現を試す
Quartoのバージョンは quarto --version で確認できます。公式リリース一覧にはQuarto 1.10.18が掲載されていますが、バージョンが一致していても、TeXやフォント、個々のプロジェクトの互換性までは保証されません。公式リリース一覧とQuartoのトラブルシューティングを参照し、診断情報を取得してから変更に進みます。
症状は「PDFが作られない」「コマンドがエラーで終了する」「PDFはできたが内容が欠けている」に分けて記録してください。症状が異なれば、確認対象も異なります。
| 見えている症状 | まず確認する箇所 | 再確認の基準 |
|---|---|---|
| PDFファイルが生成されない | コマンド、作業ディレクトリ、文書設定 | 最小文書で生成処理が完了する |
| コマンドが途中で失敗する | エラーが出た処理段階、診断出力 | 同じ入力でエラー箇所が変わるか確認する |
| PDFはできるが内容が欠ける | コード実行、字体、図表、文献 | 欠けた要素を個別に再生成して確認する |
02 文書の入口とプロジェクト設定
入力ファイルやプロジェクトの設定が原因かどうかは、どこから確認しますか。 まずQuartoが参照しているファイルと実行場所を確認します。別のディレクトリからコマンドを実行したり、想定と異なるQuartoを呼び出したりすると、設定ファイルや参照素材を見つけられないことがあります。
次に、YAMLの書式、プロジェクト設定、テンプレート、フィルターの参照先を調べます。設定を一度に複数変更せず、一項目だけ変更してから同じコマンドで再実行してください。プロジェクト設定の公式説明では、プロジェクト設定ファイルの役割が案内されています。また、renderコマンドの資料で入力文書と出力形式の指定方法を確認できます。
次のコマンドで実行環境の手掛かりを集めます。
command -v quarto
quarto --version
quarto check
command -v quarto が示す場所と、実際に意図したインストール先が異なる場合は、先にPATHやシェル設定を確認します。ここで場所が特定できないまま再インストールすると、複数の実行ファイルが残り、原因の切り分けが難しくなることがあります。
03 R・Pythonコードと文書実行
RやPythonのコードブロックが止まる場合、実行環境とPDFコンパイルのどちらが原因でしょうか。 ログに表示される最後の処理を確認し、コードの実行段階で止まったのか、実行後のPDF変換で止まったのかを区別します。コードを動かさない最小文書でPDFを作れるか試すと、問題の境界を絞れます。
文書に指定した実行エンジン、RやPythonの実行ファイル、カーネル、プロジェクトの依存関係を個別に確認します。機密データを含まない代表的なコードブロックだけを使い、同じ環境で再現するか試してください。古い出力がキャッシュや凍結済みの結果から表示されていないかも確認し、PDFに載った値を新しい実行結果だと決めつけないようにします。
再確認の際は、実行を伴わない文書の出力と、コードブロックを含む文書の出力を分けて記録します。前者が成功して後者が失敗する場合は、PDFエンジンの再設定よりも、先にコード実行環境と依存関係を調べます。
04 PDFエンジン・LaTeX・字体の切り分け
MacでLaTeXエラーが出たら、まず実際に呼び出されたPDFエンジンとそのパスを確認します。 Quartoの設定や実行環境によって使われるツールが異なるため、システムの既定エンジンが選ばれていると推測せず、診断出力とコンパイルログを確認してください。
| 症状 | ログで探す手掛かり | 低リスクの確認 |
|---|---|---|
lualatex が見つからない |
エンジン名、実行ファイルのパス | PDFエンジンの指定と実行環境を照合する |
| LaTeXの処理で停止する | 不足パッケージ、コンパイルエラー | 不足項目を確認し、既存のTeX環境で最小文書を試す |
| 日本語や記号が欠ける | エンジン、字体名、収録文字 | 指定字体の存在と必要な文字の対応範囲を調べる |
| 図表や引用が反映されない | 素材のパス、文献処理、参照エラー | 図表と引用を分けて最小文書で再出力する |
Quarto PDFレンダリングで字体が見つからない、または日本語の字形が欠ける場合は、PDFエンジン、指定した字体名、字体の収録文字を順に照合します。あるMacで表示できた字体でも、検証先の環境に存在するとは限りません。字体指定を変更した場合は、対象の日本語、記号、数式を含む短い文書で出力を確認します。PDF形式の設定資料には、PDF出力に関するオプションが掲載されています。
QuartoからlualatexやPDFエンジンを呼び出せない場合は、ログに出ている実行ファイルの名前とパスを記録します。そのうえで、プロジェクト内のエンジン指定と、現在のシェルから参照できる実行ファイルを照合してください。Quartoが管理するTinyTeXを使う場合は、既存のTeX環境と混在させず、公式のPDFエンジンとTinyTeXの案内に沿って選択肢を確認します。既存環境とTinyTeXを同時に変更すると、どの変更が結果に影響したのか追えなくなります。
既存のTeX環境で最小文書が通るなら、その環境を保ったままプロジェクト側を調べます。TinyTeXへの切り替えは、ログからTeX依存の問題が疑われる場合に限定し、切り替え前後のログを別々に保存してください。
図表が見つからない場合は、相対パス、ファイル形式、生成処理の順に確認します。参考文献や相互参照が更新されない場合は、文献ファイルの場所と処理ログを調べてください。すべての内容欠落をLaTeXの問題とみなさず、Quartoの引用と参考文献の説明も参照して、文献処理とPDFコンパイルを分けて検証します。
05 最小文書から納品確認まで
次の分岐で、どこまで調べるかを決めます。
- 最小文書でも同じPDFエラーが出る場合：実際に使われるQuartoとPDFエンジンを確認し、TeX環境を個別に検証します。
- 最小文書は成功し、元の文書だけが失敗する場合：プロジェクト設定、コード、図表、文献を一種類ずつ戻します。
- 同じ環境で症状を再現できない場合：元プロジェクトの変更を止め、データを除いた複製を隔離環境で検証します。
- PDF生成には成功したが研究内容の検証が済んでいない場合：レンダリング成功を納品完了とせず、結果と書式を別に確認します。
最小文書が通ったら、元の研究プロジェクトは直接書き換えず、複製上で確認を進めます。
- [ ] テンプレートとプロジェクト設定を戻し、PDFを再生成する
- [ ] RまたはPythonのコードと必要な依存関係を戻し、実行結果を照合する
- [ ] 図表と外部素材を戻し、配置と表示を確認する
- [ ] 文献と相互参照を戻し、本文とPDFの引用を照合する
- [ ] 最終PDFのページ、字体、図表、引用、コード結果を目視する
- [ ] 再現に使ったコマンドと環境情報を記録する
一種類を戻すたびに同じコマンドで再出力し、失敗が再発したら直前に戻した要素を確認します。機密情報を含む原本を別環境へ送らず、必要ならデータを除いた複製で検証してください。レンダリングが完了しても、分析結果の正しさや投稿先の書式要件に合うことまでは証明されません。
手元のMacだけで何度も失敗する場合、環境を修復し続けると既存の設定を崩すおそれがあり、複数のTeX環境が混在すると再現条件も見えにくくなります。反対に、同じMac環境を継続して使う必要があり、物理機器への直接接続や長期の固定運用が必要なら、レンタルが適するとは限りません。macOSが必要な一時検証では、機密情報を除いた複製プロジェクトを別環境で試す選択肢もあります。まずCALMVPSの料金と利用条件を確認し、要件に合う場合に利用環境の申し込み案内を参照してください。