What Causes FontAwesome5 Font-Expansion Errors When Compiling CVs with pdfLaTeX

pdfLaTeX fails to expand fonts because FontAwesome5 uses OpenType glyphs that lack the metric tables required for micro-typographic font expansion, causing the compiler to abort when it cannot compute expansion data.

When building the CV template in the MadsLorentzen/ai-job-search repository, users encounter fontawesome5 font-expansion errors specifically when using pdfLaTeX. This compilation failure stems from a fundamental incompatibility between pdfLaTeX's font expansion feature and the OpenType font files used by the FontAwesome5 package.

Root Cause of the Font-Expansion Error

OpenType Metrics and pdfLaTeX Expansion

The fontawesome5 package supplies icons as OpenType (OTF) glyphs. According to the source code in SETUP.md, pdfLaTeX attempts to apply font expansion—a micro-typographic feature that stretches or shrinks characters to improve text justification. Because the fontawesome5 OTF files do not contain the metric tables required for this operation, pdfLaTeX cannot compute the necessary expansion data and aborts with a font-expansion error.

Modern MiKTeX Defaults

As documented in the repository's README.md, modern MiKTeX installations enable font expansion by default. This default behavior exposes the incompatibility between pdfLaTeX and FontAwesome5, causing the error to appear specifically on updated MiKTeX distributions even when older configurations compiled successfully.

How to Resolve FontAwesome5 Font-Expansion Errors

Compile with LuaLaTeX (Recommended)

The most reliable fix is to switch to an engine that handles OpenType fonts natively. The cv/main_example.tex file in the repository is designed to compile with LuaLaTeX, which bypasses pdfLaTeX's font-expansion step entirely. For the cover letter, XeLaTeX is the recommended engine as implemented in cover_letters/cover.cls.

\documentclass{moderncv}
\usepackage{fontawesome5}
\begin{document}
\cventry{2023}{Engineer}{Acme Corp}{\faEnvelope\enspace me@acme.com}{\faPhone\enspace +1‑555‑1234}{…}
\end{document}

Run:

lualatex -interaction=nonstopmode -halt-on-error cv/main_example.tex

Disable Font Expansion in pdfLaTeX

If you must use pdfLaTeX, disable the expansion feature before loading FontAwesome5. Add \pdfadjustspacing=0 to your preamble, or load the microtype package with expansion=false.

\pdfadjustspacing=0
\usepackage{fontawesome5}

Run:

pdflatex -interaction=nonstopmode -halt-on-error cv/main_example.tex

Note that this removes micro-typographic benefits for the entire document.

Key Files in the Repository

• SETUP.md – Documents the LaTeX engine choice and explicitly notes the fontawesome5 expansion issue.
• README.md – Recommends using lualatex for the CV to avoid these errors.
• cv/main_example.tex – The CV template that includes the fontawesome5 package and triggers the error under pdfLaTeX.
• cover_letters/cover.cls – The cover letter class, which uses XeLaTeX and is not affected by this issue.

Summary

• FontAwesome5 font-expansion errors occur because pdfLaTeX cannot calculate expansion metrics for OpenType glyphs.
• Modern MiKTeX distributions enable font expansion by default, exposing this incompatibility.
• LuaLaTeX is the recommended solution, as it handles OpenType fonts without requiring metric tables.
• If stuck with pdfLaTeX, disable expansion with \pdfadjustspacing=0 or microtype options.

Frequently Asked Questions

Why does the error only appear on some MiKTeX installations?

The error appears on modern MiKTeX distributions because they enable font expansion by default. Older installations or those with custom configurations may have this feature disabled, allowing the document to compile even though the underlying metric incompatibility exists.

Can I use XeLaTeX for the CV instead of LuaLaTeX?

While the repository's cover_letters/cover.cls uses XeLaTeX, the CV template (cv/main_example.tex) is optimized for LuaLaTeX. XeLaTeX handles OpenType fonts similarly to LuaLaTeX and would theoretically work, but the repository documentation specifically recommends LuaLaTeX for the CV to ensure compatibility with all moderncv features.

Will disabling font expansion affect my document's appearance?

Disabling font expansion with \pdfadjustspacing=0 removes micro-typographic benefits for the entire document, potentially resulting in looser word spacing and less optimized justification. This trade-off is necessary only if you absolutely must use pdfLaTeX instead of LuaLaTeX.

Is there a way to use FontAwesome5 with pdfLaTeX without losing micro-typography?

No. Because FontAwesome5 relies on OpenType fonts that lack the necessary metric tables for expansion, pdfLaTeX cannot apply micro-typography to these glyphs. The only way to maintain micro-typographic features is to switch to LuaLaTeX or XeLaTeX, which handle OpenType fonts natively without requiring the expansion calculations that cause pdfLaTeX to fail.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}