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

> Learn why FontAwesome5 causes font expansion errors in pdfLaTeX. Discover how missing metric tables prevent micro-typographic expansion and halt CV compilation.

- Repository: [Mads Lorentzen/ai-job-search](https://github.com/MadsLorentzen/ai-job-search)
- Tags: troubleshooting
- Published: 2026-07-12

---

**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`](https://github.com/MadsLorentzen/ai-job-search/blob/main/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`](https://github.com/MadsLorentzen/ai-job-search/blob/main/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`.

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

```

Run:

```bash
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`.

```tex
\pdfadjustspacing=0
\usepackage{fontawesome5}

```

Run:

```bash
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`](https://github.com/MadsLorentzen/ai-job-search/blob/main/SETUP.md)** – Documents the LaTeX engine choice and explicitly notes the `fontawesome5` expansion issue.
- **[`README.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/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.