Troubleshooting

When something breaks, collect these first:

lualatex --version
latexmk --version
biber --version
kpsewhich moderndoc.sty

If minted is enabled:

pygmentize -V || true

---

1) “File X.sty not found”

Install missing packages:

tlmgr install X

If you’re missing ModernDoc itself:

• confirm it is installed under TEXMFHOME
• run mktexlsr

---

2) “fontspec error: cannot-use-pdftex”

You compiled with pdfLaTeX.

Use LuaLaTeX:

latexmk -lualatex --shell-escape main.tex

---

3) Minted errors

Shell escape missing

latexmk -lualatex --shell-escape main.tex

Pygments missing

python3 -m pip install --user Pygments

Disable minted

\usepackage[minted=false]{moderndoc}

---

4) Bibliography not appearing

Checklist:

• \addbibresource{references.bib} exists
• \printbibliography exists
• biber runs successfully

Manual cycle:

lualatex --shell-escape main.tex
biber main
lualatex --shell-escape main.tex
lualatex --shell-escape main.tex

---

5) Debugging technique that works

Rebuild with file/line error reporting:

latexmk -lualatex --shell-escape -interaction=nonstopmode -file-line-error main.tex

Then open main.log and fix the first real error. Everything after that is usually cascading.