How to Troubleshoot KOMA-Script and moderncv
At a glance
- 1. Check the class
Use one document class: moderncv for its CV layout, or komacv for a KOMA-Script-based CV.
- 2. Build a minimal file
Temporarily remove extra packages and commands, then compile a small working example.
- 3. Read the first error
Fix the earliest LaTeX error in the log; later errors are often consequences.
- 4. Add features gradually
Restore packages and customizations one at a time to identify the conflict.
The phrase “KOMA-moderncv” can refer to a few different setups, and without a LaTeX error message there is no single fix to apply. The most common cause of trouble is mixing instructions for moderncv, which is its own document class, with instructions for KOMA-Script classes such as scrartcl or scrreprt.
Start by checking the \documentclass line. Use exactly one class. The example below is a minimal moderncv document; if it compiles, add your own content and packages back in stages.
Choose one CV class
For a CV in the moderncv style, use the moderncv class. Its layout and commands are designed to work together:
\documentclass[11pt,a4paper,sans]{moderncv}
\moderncvstyle{classic}
\moderncvcolor{blue}
\name{Jane}{Doe}
\title{Curriculum Vitae}
\address{12 Example Street}{Example City}{United States}
\email{jane.doe@example.com}
\begin{document}
\makecvtitle
\section{Education}
\cventry{2020--2024}{BSc in Mathematics}{Example University}
{Example City}{}{Graduated with distinction.}
\end{document}
Save the file with a .tex extension and compile it with a standard LaTeX engine such as pdfLaTeX. The class line selects moderncv; \moderncvstyle and \moderncvcolor select the design; \makecvtitle prints the contact information and title. The \cventry command takes six required arguments: dates, degree or role, institution or employer, location, a detail field (which can be left empty), and a description; it also has an optional leading spacing argument.
If instead you want a CV whose underlying class is based on KOMA-Script, use a class intended for that purpose, such as komacv, and follow that class’s own documentation. A KOMA-Script article class is not a substitute for a CV class: scrartcl gives you an article layout, not moderncv’s CV commands and design.
Avoid combining document classes
A LaTeX document has one \documentclass declaration. These are alternatives, not lines to use together:
\documentclass{moderncv}
\documentclass{scrartcl} % Do not add a second class
Likewise, moderncv is not normally enabled by writing \usepackage{moderncv} in a KOMA-Script document. If you use \documentclass{scrartcl}, you can build a CV yourself with KOMA-Script features, but you should not expect commands such as \makecvtitle or \cventry to exist unless you separately define or obtain them.
Find the source of the error
When your file fails, make a copy and reduce it to the smallest example that still fails. Keep the class line, required CV commands, and only the packages needed to reproduce the problem. Then:
- Compile the minimal file before adding custom styling.
- Read the log from the beginning and locate the first error, not just the last one.
- Check the line named in the error and the lines immediately before it; a missing brace or environment ending can make a later line appear responsible.
- Add your packages and custom commands back one at a time, recompiling after each addition.
This process separates a class-selection problem from a package conflict or a typo in the CV content. If the minimal moderncv example works but your full file does not, the issue is likely in an added package, option, or command rather than in the basic class setup.
Common mistakes
- Using two classes. Keep only one
\documentclassline. Choose moderncv, komacv, or a KOMA-Script article class according to the layout you want. - Treating a class as a package.
moderncvis selected with\documentclass, not loaded as an ordinary package insidescrartcl. - Copying commands from a different class. Commands such as
\cventrybelong to moderncv-style CV workflows; they are not standard KOMA-Script commands. - Adding every package at once. Start with the class’s minimal example. Some packages alter page layout, fonts, or headers and may conflict with a CV class’s own formatting.
- Fixing the last error first. One early syntax error can trigger many later messages. Resolve the first meaningful error, then compile again.
If you still cannot isolate the problem, share a minimal file that reproduces it, the exact error text, and the compiler you used. Avoid posting a full CV containing private contact details; replace them with example text first.
References
Spotted an error? Send a correction. Read how we write and check articles in our editorial policy.