Fixing problems

When you need this page: When stuck

Errors are normal, and most take a minute once you know where to look. The fastest route: paste the error into Explain my error. Or find it in common messages, ask an AI chat, or ask for help.

On this page

When a compile stops

A failed compile never changes your files. Your writing is exactly as you left it.

In words: find the first error, look at the file and line it names (and the line before), check the usual culprits, fix, and compile again.

Where the errors are:

VS Code: View → Problems lists each error with its file and line; click one to jump there. The full log is in the Output panel, under LaTeX Compiler.
Overleaf: the Logs and output files button beside Recompile lists the errors; click one to jump there. Raw logs, at the bottom of that list, shows the full log.
Another editor: look for its log or messages panel, or open main.log (in build/ or next to main.tex).

Compile after each small change so you know what caused a problem. A warning still produces a PDF, but review warnings before you submit.

Read an error message

LaTeX errors look long, but the useful part is short. This is the real error from the sample thesis after one typo, \parencit instead of \parencite in chapter 1:

./chapters/01-introduction.tex:13: Undefined control sequence.
l.13 example~\parencit
                      {lamport1994}. Replace it with literature relevant to ...

The file: chapters/01-introduction.tex. Open this file, not main.tex.
The line: 13, the number after the file name.
The message: "Undefined control sequence" means LaTeX does not know a command, usually because of a typo after a backslash.
Where it stopped: the line starting l.13 ends where LaTeX stopped reading, so the last thing on it, \parencit, is the problem.

Fix: write \parencite{lamport1994} and compile again. With several errors, fix only the first; the later ones are often side effects.

Ask an AI chat to explain it

An AI chat is a quick way to decode a cryptic error. Paste the first error and the few lines around it (or the whole log from your editor or Overleaf), and say whether you use Overleaf or your computer. Never paste confidential or unpublished material. Try one change, compile, and undo it if the PDF gets worse.

Here is the first LaTeX error and a short example. I use Overleaf (or: my computer, with macOS/Windows/Linux). Explain what it means and suggest the smallest fix. Keep my text, data, citations, and template formatting unchanged. Show the lines to change.

More, including assistants that can edit your files and prompts for setup, errors, and conversions: AI for technical help. A web search or Overleaf Learn (opens in a new tab) works too.

Clean recompile

A clean recompile throws away LaTeX's scratch files and builds everything again. Try it when the PDF will not update, numbers stay as ??, or an error looks impossible. It never changes your writing.

Overleaf: open the Recompile menu (the small arrow beside the button) and choose Recompile from scratch. To change the engine, open Settings (the gear icon) and, under Compiler, pick pdfLaTeX, XeLaTeX, or LuaLaTeX (Overleaf: selecting a compiler (opens in a new tab)).
VS Code: open the Command Palette (Ctrl+Shift+P, or Cmd+Shift+P on macOS), run LaTeX Workshop: Clean up auxiliary files, then compile again. To change the engine, run LaTeX Workshop: Build with recipe and pick RPI Thesis Toolkit: XeLaTeX + Biber (Unicode) or LuaLaTeX + Biber (Unicode) (Biber is the bibliography step). Saving keeps using that choice until you close VS Code; after you reopen it, pick it again the same way.
TeXShop, TeXstudio, or TeXworks: each editor has its own way to remove auxiliary files and to choose an engine, and the steps differ by version. Look in that editor's own documentation (TeXShop (opens in a new tab), TeXstudio (opens in a new tab), TeXworks (opens in a new tab)). Then run the steps from Get started again.
Optional, in a terminal: see build commands.

Switch engine only to fix characters pdfLaTeX cannot handle, then check the whole PDF (compile engines).

Common messages

The same table drives Explain my error and the optional build helper, so all three give the same advice.

Setup and files

What you see	What it means and what to try
File `rpi-thesis.cls' not found	LaTeX cannot find the class file, so it is not compiling the starter's folder. Extract the whole ZIP and open the folder that contains `main.tex`. In an editor on your computer: Open the folder itself (File, Open Folder in VS Code), not only `main.tex`. On Overleaf: `main.tex` and `rpi-thesis.cls` must be at the top of the file list, not inside a folder.
`Missing title in metadata.tex (or author, department, ...)`	A required setting in `metadata.tex` is empty or missing. Fill in that setting inside `\thesissetup{...}` in `metadata.tex`, then compile again. More: All thesis settings.
`Committee chair is missing`	No `\committeemember` line in `metadata.tex` has the role `[Chair]` or `[Co-Chair]`, spelled exactly so. Put `[Chair]` (or `[Co-Chair]`) on one `\committeemember` line: `[chair]` is not recognized. More: All thesis settings.
`You have requested ... version ... of document class rpi-thesis`	Your `rpi-thesis.cls` is older than the rest of your starter files. Copy `rpi-thesis.cls` from the newest starter into your thesis folder, replacing the old one. More: Update the formatting safely.
`Unknown setting "..." in metadata.tex`	A setting name inside `\thesissetup{...}` is misspelled or does not exist. Correct its spelling; every setting is listed in All thesis settings. More: All thesis settings.
`Unknown degree choice`	The degree setting in `metadata.tex` has a value the class does not know. Use masters, doctoral, or engineering-doctorate, in lower case. More: All thesis settings.
`Unknown graduation month`	The graduation-month setting in `metadata.tex` has a value the class does not know. Use May, August, or December, with a capital first letter. More: All thesis settings.
`Graduation year must have four digits`	The graduation-year setting in `metadata.tex` is not a four-digit year. Write the year like 2027. More: All thesis settings.
`RPI seal not found`, or a seal placeholder on the title page	The seal belongs to RPI, so the starter does not include it; the title page keeps a box of the same size in its place. Download the seal from RPI's Thesis Preparation page and save it as `assets/rpi-seal.jpg`, then compile again. On Overleaf: Upload the seal into the assets folder in the file list. More: Add the RPI seal.
`Unsupported class option`	`main.tex` gives the class an option in square brackets, such as [11pt]; this class takes none. Use `\documentclass{rpi-thesis}` with no options; settings go in `metadata.tex`. More: All thesis settings.
LaTeX Error: File `figures/...' not found	A figure file named in `\includegraphics` is missing. Check the file name, capital letters, extension, and folder (`figures/...`). In an editor on your computer: Compare the name in `\includegraphics` with the file in the figures folder. On Overleaf: Upload the picture into the figures folder in the file list, then compare its name with the one in `\includegraphics`.
LaTeX Error: File `chapters/....tex' not found	A file named in `\include` or `\input` does not exist under that name. Check the file name and folder in the `\include` or `\input` line in `main.tex`: write it without .tex, with the same capital letters as the file.
`Could not set up appendices`	A line above `\documentclass` in `main.tex`, or an outdated LaTeX installation, changed `\chapter`. Remove lines added above `\documentclass`, or update TeX Live.
A file can't be found, and the folder is in OneDrive or iCloud or its path has non-English letters	A synced folder may keep a file only online, and some LaTeX tools cannot read a path with non-English letters. Set the folder to Always keep on this device, or move it to a short, plain path such as `C:\thesis` or `~/thesis`.

Citations and references

What you see	What it means and what to try
`Misplaced alignment tab character &`	An & is outside a table; most often a title in the .bib file contains &. Write it as `\&`.
`Please (re)run Biber on the file`	The bibliography step has not run since your last change, so citations show as keys in bold. Compile again. In an editor on your computer: VS Code with the starter's settings runs Biber for you; in other editors run the bibliography step yourself (Get started, Other editors). On Overleaf: Recompile; Overleaf runs Biber for you. More: Other editors.
Citation `...' undefined, or Reference `...' undefined, or ?? or a bold citation key in the PDF	A citation or cross-reference is not known yet: it fills in on a later compile, or its key does not match. Compile again. Still there? Check that the key in `\parencite` or `\ref` matches `references.bib` or the `\label` exactly, then compile again. In an editor on your computer: VS Code with the starter's settings runs the bibliography step for you; in other editors run it yourself (Get started, Other editors). More: Bold citation keys and question marks.
The reference list is empty	The reference list shows only the entries you cite. Cite at least one entry, for example with `\parencite{key}`, then compile again.
A new Zotero source doesn't appear	The .bib file in your thesis folder does not have the new source yet, or its key differs from the one you cite. Export again from Zotero, compile again, and check that the key in your citation command matches the key in the .bib file exactly. More: Collect and cite sources with Zotero.
`File 'main.bbl' not created by biblatex`	A bibliography file left from an earlier build, often one that used BibTeX or natbib, is still in the folder. Do a clean recompile, then build again. In an editor on your computer: In VS Code, run LaTeX Workshop: Clean up auxiliary files; with the build helper, python3 scripts/build.py --fresh. On Overleaf: Open the Recompile menu and choose Recompile from scratch. More: Clean recompile.
`Label(s) may have changed. Rerun to get cross-references right`	Numbers, references, or bookmarks changed in this run; the next compile settles them. Compile again.

Layout and the PDF

What you see	What it means and what to try
`Undefined control sequence`	LaTeX does not know a command, usually because of a typo after a backslash, such as `\parencit` for `\parencite`. Look at the end of the l. line: the last command there is the one LaTeX does not know. Correct its spelling, or load the package it comes from. More: Read an error message.
`Missing $ inserted`	A math-only character or command, often an underscore _ or ^, is outside $...$ . Write `\_` for an underscore in text, or put the math between $ signs.
`Runaway argument, or a brace error`	A { has no matching }, or there is one } too many. Check your last edit near the line shown for a missing or extra }.
`Environment ... undefined, or \begin{...} ended by \end{...}`	The name in `\begin{...}` is misspelled, its package is not loaded, or a `\begin{...}` and its `\end{...}` do not match. Check that each `\begin{name}` has an `\end{name}` with the same spelling, in the right order. More: Read an error message.
`Missing character: There is no ... in font ...`, or a special character (such as an accented letter, or one from another alphabet) is missing or garbled	The font or compile engine has no shape for that character. Use a LaTeX accent command, such as `\'e` for an e with an acute accent, or try another compile engine. More: Choose a compile engine.
`STIX Two Math font not found`	LuaLaTeX or XeLaTeX could not find a fallback math font, so a few symbols, such as `\bigstar`, `\digamma`, and `\subseteqq`, may be blank. Update your full LaTeX installation, do a clean recompile, then check the affected math. On Overleaf: Choose the newest TeX Live version in Overleaf's Settings, then do a clean recompile.
`Overfull \hbox`	Something is wider than the text area: a long URL, table, equation, or image. Find it in the PDF and resize or break it. More: Too wide for the page?.
`Overfull \vbox`	Something is taller than the page: on the title page, usually the title or a committee line; elsewhere, a large figure or table. On the title page, remove manual line breaks from the title and check long names and committee lines. Elsewhere, make the largest figure or table on that page smaller.
A figure floats to a different page	This is normal: LaTeX places figures and tables where they fit. Use `[htbp]` after `\begin{figure}` and write Figure~`\ref{...}` in the text, not "below". More: Add a figure.
An edit, the contents, or the references do not update	You may be looking at an old copy of the PDF, or a scratch file from an earlier compile is in the way. Save every file and check that you are viewing the new PDF. Still stale? Do a clean recompile. More: Where the PDF ends up.
`Pre-submission hints (your PDF was built; check these before submitting)`	Your PDF was built. The build helper found things to check before you submit, such as a web source with no access date. Fix each listed line before submitting. More: Build commands.
`Unicode character ... not set up for use with LaTeX`	pdfLaTeX cannot print one character in your text, often a symbol or letter pasted from Word or the web. The message names it, and the l. line ends with it. Replace that character with a LaTeX command (for example $`\geq`$ for the greater-than-or-equal sign), or compile with LuaLaTeX and check the PDF: its font must have the character. More: Going further, Choose a compile engine.
`Underfull \hbox (badness ...)`	LaTeX stretched the spaces in a line or page, often after \\ or `\linebreak`. Usually harmless. Look at those lines in the PDF; remove a manual line break if the spacing looks wrong.

Tools and installs

What you see	What it means and what to try
`latexmk, pdflatex, or biber not found, or spawn latexmk ENOENT`	A LaTeX tool (latexmk, the engine, or Biber, the bibliography tool) is not installed, or your editor started before the installation finished. Finish installing the full LaTeX distribution, then quit your editor completely and reopen it (on Windows, restart the computer if needed). In an editor on your computer: On Linux, use VS Code's .deb or .rpm, not the Flatpak. The optional build helper's setup check names the missing tool. On Overleaf: Overleaf has every tool; this message comes from a LaTeX installation on a computer.
LaTeX Error: File `....sty' not found	A package named in `\usepackage` is not installed, or its name is misspelled. Check the spelling in `\usepackage`; if it is right, install the full LaTeX distribution or update it. On Overleaf: Overleaf has nearly every package: check the spelling in `\usepackage`.
`latexmk: could not find the script engine 'perl'`	latexmk needs Perl, which MiKTeX does not include. Install TeX Live instead (https://tug.org/texlive/ (opens in a new tab)), or install Perl and restart.
VS Code says Restricted Mode, or LaTeX Workshop does nothing	VS Code turns off extensions such as LaTeX Workshop in a folder you have not trusted. Click Restricted Mode in the status bar and choose Trust.
Overleaf says the compile timed out	The project took longer to compile than Overleaf allows; large images are a common cause. Try Fast [draft] from the Recompile menu, shrink large photos, export plots as PDF, or compile on your computer. Fast draft shows images as empty boxes, so switch back to Normal and check every figure and the seal before you share or submit.
`Package fontspec Error: The font "..." cannot be found`	LuaLaTeX or XeLaTeX cannot find a font: the LaTeX installation is not the full one, or a font name added in `preamble.tex` is misspelled. Install or update the full LaTeX distribution. If you named a font yourself, check its exact name, or remove that line to use the class's font. On Overleaf: Choose the newest TeX Live version in Overleaf's Settings, then recompile.

Rare messages: an old LaTeX installation, version mismatches, the bibliography step on a Mac, typed build commands

What you see	What it means and what to try
`You have requested release '...' of LaTeX`	Your LaTeX is older than this class needs (TeX Live 2022 or newer). Install the current full TeX Live (https://tug.org/texlive/ (opens in a new tab)), or use Overleaf. On Overleaf: Choose the newest TeX Live version in Overleaf's Settings, then recompile.
`Found biblatex control file version ..., expected version ...`	This is most often a stale control file left by an earlier build. Do a clean recompile, then build again. If it still fails, Biber and biblatex come from different TeX installations or years: use one TeX distribution, update it completely, and make sure 'biber' is the one it installed. In an editor on your computer: In VS Code, run LaTeX Workshop: Clean up auxiliary files; with the build helper, python3 scripts/build.py --fresh. On Overleaf: Open the Recompile menu and choose Recompile from scratch. More: Clean recompile.
`biber ... lipo (on a Mac)`	Biber, the bibliography tool, could not start: older Mac builds of Biber fail on newer macOS. Your thesis is fine. Update TeX Live, then compile again. In an editor on your computer: On macOS (MacTeX), open TeX Live Utility (Applications, TeX) and choose Update all packages, or run 'sudo tlmgr update --self --all'. On Linux with apt, update with your package manager, for example 'sudo apt update' then 'sudo apt upgrade'. On Overleaf: Overleaf installs Biber for you; this message comes from a LaTeX installation on a computer.
I can't write on file `chapters/...aux'	LaTeX cannot create a chapter's .aux file, because that chapter's folder does not exist where LaTeX writes its scratch files. Do a clean recompile. If you typed your own build command, use one from the build commands instead. More: Build commands.

Please don't make an error disappear by changing margins, spacing, or the class file. Adjust the object instead, or ask for help.

Ask for help

Stuck on something odd? You are probably not the first, and your question helps everyone writing after you. Questions about LaTeX, Zotero, files, or "where does this go?" are all welcome.

Make it easy to see. On Overleaf, create a view-only link from the share menu. On your computer, make the smallest made-up example that still shows the problem.
Copy the first error, with its file and line number.
Send it through either channel:
- No account needed: the help and feedback form (opens in a new tab).
- With a GitHub account: open an issue with the LaTeX help or bug form. Answers stay public and searchable. Never opened one? See how to open an issue.

Copy and fill in:

Where I write:   Overleaf / VS Code / other editor: ...
Computer:        macOS / Windows / Linux
What I did:      ...
What I expected: ...
What happened (first error, with file and line): ...
View-only link or small example: ...

Warning

Remove unpublished research and personal details before sharing. A view-only link shows your whole project, so share it only with someone you trust, then turn link sharing off.

Found a fix or a tip worth passing on? The form takes those too, and ways to contribute lists other options.

Something wrong or unclear on this page? Tell the maintainer (opens in a new tab), no account needed.