How to Troubleshoot LaTeX Errors with moderncv

A moderncv error can come from the document class, a font package, an incompatible LaTeX engine, or a problem elsewhere in the CV. The title alone does not identify which one occurred, so begin with the first real error in the compiler log rather than the final message.

The example below is a small baseline for pdfLaTeX. If it compiles, add your original packages and CV content back a little at a time until the error returns.

Start with a minimal moderncv document

Save this as cv.tex and compile it with pdflatex cv.tex:

\documentclass[11pt,a4paper,sans]{moderncv}

\usepackage[T1]{fontenc}
\moderncvstyle{classic}
\moderncvcolor{blue}

\name{Jane}{Doe}
\title{Curriculum Vitae}
\email{jane.doe@example.com}

\begin{document}
\makecvtitle

\section{Experience}
\cventry{2020--2024}{Researcher}{Example Institute}{City}{}
  {Worked on a research project and presented the results.}

\end{document}

This example uses moderncv’s classic style and a standard pdfLaTeX font encoding. It does not require you to load fontspec. If this file fails, check that moderncv is installed and that your TeX distribution is up to date. If it succeeds, the cause is likely in an added package, font setting, or piece of document content.

Read the log from the top

Search the .log file or terminal output for the first line beginning with !. That is often the useful diagnostic. Messages such as Emergency stop can appear afterward because LaTeX has already stopped; they are generally not the root cause. Also read the file and line number printed near the first error.

For example, an error saying that fontspec requires XeTeX or LuaTeX points to an engine mismatch: the document is using fontspec but was compiled with pdfLaTeX. An error saying a font cannot be found may mean that the requested font is not installed or its name is wrong.

Match the font setup to the engine

Choose one engine and use the font configuration intended for it:

Engine	Typical font approach
pdfLaTeX	Use LaTeX font packages and, for example, \usepackage[T1]{fontenc}. Do not load fontspec.
XeLaTeX or LuaLaTeX	Use fontspec when selecting system fonts. Do not load fontspec while compiling with pdfLaTeX.

If you switch engines, remove packages and commands that only apply to the previous engine. For instance, a document that uses \setmainfont{...} needs XeLaTeX or LuaLaTeX, and the chosen font must be installed and available to that engine. Do not add several font packages as a trial-and-error fix; they can conflict or obscure the actual problem.

Distinguish errors from line-breaking warnings

A message such as Overfull \hbox usually means that some text extends beyond the line width. It is a warning, not normally a compilation failure. Moderncv layouts can make long URLs, email addresses, or uninterrupted text in an entry especially noticeable.

Find the affected line in the log and shorten or rephrase the text if possible. For a long URL, use a URL-aware command such as \url{...} when available, or choose a sensible place to split it. You can also give TeX a little more flexibility for line breaks by adding this to the preamble:

\emergencystretch=2em

This can reduce overfull lines, but it does not fix a genuine error or make every unbreakable string fit. Avoid inserting \\ throughout prose just to force wrapping: it creates explicit line breaks and can produce awkward spacing or layout problems.

Add your CV back in stages

Once the baseline compiles, restore your document incrementally. Add your packages first, then the personal details and sections, and finally longer entries. Compile after each change. If the failure reappears, the most recent change is a useful place to look. Check especially for packages loaded twice, font commands meant for a different engine, and examples copied from documentation for a different moderncv version.

When asking for help with a remaining error, include the first error message and a minimal file that reproduces it. Also state the engine and how you compile the document. A screenshot or the final Emergency stop line alone usually omits the information needed to diagnose the cause.

Common mistakes

• Fixing the last log message instead of the first: later errors may just follow from the original failure.
• Treating a line-width warning as a fatal error: Overfull \hbox generally means the PDF was produced, but some text did not fit neatly.
• Mixing font engines: fontspec is for XeLaTeX or LuaLaTeX, not pdfLaTeX.
• Changing many things at once: if you alter the engine, packages, fonts, and CV content together, it becomes hard to tell which change mattered.
• Using a forced line break as a universal fix: \\ does not repair font configuration or other compilation errors.