FAQ

Some LaTeX problems announce themselves with a line beginning !. The expensive ones do not. A reference that stays ?? however often you compile; a figure that lands two pages late; a PDF that comes out A4 after the source clearly said letterpaper; a manuscript that builds here and fails on a co-author’s machine. This FAQ collects only those cross-cutting questions — the ones that span several mechanisms at once — and answers each by describing what actually happens during the run. Problems that a single error message settles have their own pages; the index at the end points to them.

Why LaTeX has to be compiled twice

Because LaTeX reads the source front to back exactly once and cannot look ahead. When it typesets \ref{sec:first} on page 1, the number that \label will eventually carry is not known yet. So \label writes the number into the .aux file, and \ref reads the .aux left behind by the previous run. Measured on TeX Live 2024, the first run prints LaTeX Warning: Reference 'sec:first' on page 1 undefined on input line 4. and LaTeX Warning: There were undefined references., and the PDF genuinely reads “See Section ?? on page ??.” The .aux at that point contains \newlabel{sec:first}{{1}{1}{}{}{}}, which the second run picks up to produce “See Section 1 on page 1.” A ?? is therefore not damage — it is a sign that you are still on lap one.

$ pdflatex ref.tex        # run 1
LaTeX Warning: Reference 'sec:first' on page 1 undefined on input line 4.
LaTeX Warning: There were undefined references.
LaTeX Warning: Label(s) may have changed. Rerun to get cross-references right.

$ pdftotext ref.pdf -
See Section ?? on page ??.

$ pdflatex ref.tex        # run 2 — no warnings
$ pdftotext ref.pdf -
See Section 1 on page 1.

The warning that closes the run — LaTeX Warning: Label(s) may have changed. Rerun to get cross-references right. — is LaTeX reporting that the .aux it just wrote differs from the one it read. The important part is that two passes are a floor, not a rule. One extra digit can reflow a line, which changes a page number, which changes the .aux again; with a table of contents, a list of figures, or hyperref bookmarks in play, three or four passes are entirely ordinary. latexmk exists for precisely this: it repeats until the .aux stops changing. So stop counting passes by hand and let it iterate. Conversely, never chase a ?? before you have compiled twice. If it survives two passes, the \label is misspelled, missing altogether, or a stale .aux is in the way — deleting the .aux puts you back on run one.

Why the bibliography never appeared

Because bibliographies are handled by a separate program outside LaTeX, and one full cycle takes four commands. bibtex never reads your .tex. It reads the \citation and \bibdata lines that LaTeX wrote into the .aux, pulls the matching entries out of the .bib, and produces a .bbl. Measured on TeX Live 2024 the stages are unmistakable. The first pdflatex prints LaTeX Warning: Citation 'knuth1984' on page 1 undefined, and the PDF reads “As shown by [?].” with no reference list at all. Running bibtex reports its inputs: The top-level auxiliary file: doc.aux, The style file: plain.bst, Database file #1: refs.bib. The second pdflatex does print the References list — yet the in-text citation is still [?]. Only the third run turns it into [1].

pdflatex doc     # writes \citation and \bibdata into doc.aux; text shows [?]
bibtex   doc     # reads doc.aux + refs.bib, writes doc.bbl
pdflatex doc     # pulls in doc.bbl: the list appears, the mark is still [?]
pdflatex doc     # now the \bibitem labels are in doc.aux: the mark becomes [1]

latexmk -pdf doc # does all four, and repeats until nothing changes

The need for a third pass follows from the same .aux round trip. The \bibitem entries in the .bbl that run two reads write the “this key is [1]” mapping into the .aux — but they do so partway through that same run, after the \cite in the body has already been typeset. The mapping is therefore usable only from the next run onward, which is why a third pdflatex, the fourth command overall, is required. biblatex with biber has the same shape; biber replaces bibtex and reads a .bcf instead. In practice, hand the whole thing to latexmk and stop counting. If the list is still empty, the cause is almost always one of three: \bibliography{refs} written with the .bib extension, no \cite anywhere in the body (add \nocite{*} to list everything), or a mistyped key. The last one shows up in the .blg log as Warning--I didn't find a database entry for "...".

Why the figure landed on the wrong page

Because a figure is a float: LaTeX holds it back until a page has room for it. The place most people come unstuck is the difference between \newpage and \clearpage. \newpage merely ends the current page — it does not flush the waiting floats. \clearpage outputs every pending float first and only then ends the page. Compiling two versions of one source on TeX Live 2024, differing in that single command, and reading the result page by page with pdftotext, makes the consequence unmistakable.

\section{Alpha}
... a page of text ...
\begin{figure}[t]
  \centering \rule{10cm}{16cm}
  \caption{First figure}
\end{figure}

\newpage      % <- only this line differs between the two builds
%\clearpage

\section{Beta}
\begin{figure}[t]
  \centering \rule{6cm}{5cm}
  \caption{Second figure}
\end{figure}
Text of Beta.

The \newpage build came out four pages long: p.1 the body of Alpha, p.2 the “Beta” heading and its text, p.3 Figure 1, p.4 Figure 2. Figure 1, which belongs to Alpha, jumped over the next section heading and surfaced behind it. The \clearpage build is three pages: p.1 the body of Alpha, p.2 Figure 1 alone, p.3 Figure 2 together with the “Beta” heading and its text. The figure no longer crosses a section boundary, and the document is a page shorter as well. So most cases of “my figure ended up in the wrong chapter” trace back to a \newpage at a structural break. Use \clearpage at chapter and section breaks (\cleardoublepage for two-sided printing). Beyond that, write [htbp] rather than a bare [h] — [h] means “here if it fits, otherwise later”, and a float taller than \textheight can never share a page with text at all. Fine control of floats belongs to the floats and placement page.

Why the image did not appear, or came out as an empty box

If nothing appears at all, suspect a mismatch between image format and output route; if an empty box appears, suspect draft. pdflatex reads PDF, PNG and JPEG directly and cannot read EPS at all — convert it with epstopdf, or let the epstopdf package do it. The DVI route, platex then dvipdfmx, does handle EPS. When the file cannot be found the message is ! LaTeX Error: File 'fig.eps' not found., and the cause is nearly always a forgotten extension, a wrong path, or a \graphicspath{{figures/}} written without its trailing slash. The other classic, ! LaTeX Error: Cannot determine size of graphic in xxx.png (no BoundingBox)., appears when graphicx was never told which driver it is running under — Cloud LaTeX’s own FAQ lists that single message as an entry of its own.

The empty-box case is almost anticlimactic once you know it. Building a document with \documentclass[draft]{article} on TeX Live 2024 and running pdftotext over the result returned the file name as text where the picture should have been. That is exactly what draft does: it skips rendering the image and leaves a frame of the same dimensions carrying the name. Forgetting a draft in the class options and then concluding that the images are broken is one of the commonest accidents in LaTeX. Always take draft out for the submitted version; if you only want the speed, \usepackage[draft]{graphicx} limits the effect to the graphics. And if the figure is still absent after every cause in this section has been ruled out, it may not be missing at all — it may have floated onto another page. Go back one section.

Why it builds for me but not for my co-author

The differences between two machines come down to three things in practice: the TeX Live year, the versions of the installed packages, and your own files sitting in a personal tree. The first two become visible by adding one line. Put \listfiles before \documentclass and the .log ends with a *File List* block giving one line per file, with date and version — on TeX Live 2024, entries such as amsmath.sty 2023/05/13 v2.17o AMS math features and graphicx.sty 2021/09/16 v1.2d Enhanced LaTeX Graphics. Ask the co-author for the same block, diff the two, and the culprit is usually a single line. The engine’s own vintage comes from pdflatex --version, which answers pdfTeX 3.141592653-2.6-1.40.26 (TeX Live 2024).

% put this on the very first line of the source
\listfiles

$ pdflatex doc.tex && sed -n '/File List/,/^ \*\*\*/p' doc.log
 *File List*
 article.cls    2023/05/17 v1.4n Standard LaTeX document class
 amsmath.sty    2023/05/13 v2.17o AMS math features
graphicx.sty    2021/09/16 v1.2d Enhanced LaTeX Graphics (DPC,SPQR)

$ kpsewhich -var-value=TEXMFHOME   # macOS, TeX Live 2024
/Users/you/Library/texmf

$ pdflatex --version | head -1
pdfTeX 3.141592653-2.6-1.40.26 (TeX Live 2024)

The third cause, the personal tree, is the hardest to spot. Running kpsewhich -var-value=TEXMFHOME under TeX Live 2024 on macOS returns /Users/you/Library/texmf — the texmf.cnf shipped with TeX Live 2024 sets TEXMFHOME = ~/Library/texmf, whereas the default on Windows and Linux is ~/texmf. Any .sty, .bst or private font living there is visible only on your machine, so the person you sent the manuscript to gets ! LaTeX Error: File 'mystyle.sty' not found. The remedy is blunt: keep home-made files in the manuscript folder and ship them with it. If you need to erase the TeX Live year difference as well, pin the environment itself with something like a Docker image. Working practices for co-authorship belong to the collaboration page, and pinning an environment to the Docker and CI page.

Why the PDF says A4 when the source asked for letterpaper

Because a class option changes the type area — the text block and its margins — not the paper of the PDF itself. Compiling \documentclass[letterpaper]{article} as-is on TeX Live 2024 and running pdfinfo returns Page size: 595.276 x 841.89 pts (A4). The reason lies in pdfTeX’s start-up configuration. The pdftexconfig.tex that is dumped into the format sets \pdfpageheight = 297 true mm and \pdfpagewidth = 210 true mm, and those are primitives that fix the PDF media box. A class option cannot reach that layer. Add \usepackage[letterpaper]{geometry} to the same document and the answer changes to 612 x 792 pts (letter), because geometry looks after the type area and the sheet size together.

$ pdflatex letter.tex && pdfinfo letter.pdf | grep "Page size"
Page size:       595.276 x 841.89 pts (A4)      # \documentclass[letterpaper]{article}

# fix 1 — geometry sets the type area AND the sheet
%   \usepackage[letterpaper]{geometry}
Page size:       612 x 792 pts (letter)

# fix 2 — set the pdfTeX primitives before \documentclass
%   \pdfpagewidth=8.5truein \pdfpageheight=11truein
Page size:       612 x 792 pts (letter)

There are three fixes, and the situation picks one. The most straightforward is geometry, which also lets you state the margins in the same place. If you would rather not grow the preamble, writing \pdfpagewidth=8.5truein \pdfpageheight=11truein before \documentclass produces the same 612 x 792 pts (letter) — measured. On the DVI route it is dvipdfmx that actually makes the PDF, so the size is given at conversion time, as in dvipdfmx -p letter. It is worth knowing why true is attached to those lengths: when the whole document is scaled with \mag, only dimensions marked true stay immune to the scaling. The details of paper handling belong to the page on producing PDF.

Why Japanese does not appear, or comes out garbled

It is almost always the wrong engine or the wrong file encoding. pdflatex cannot set Japanese at all. There are two working routes: uplatex (with a jsarticle or jlreq class) handing off to dvipdfmx, or lualatex with luatexja. Save the source as UTF-8. What people miss is that “supports Japanese” is not one thing: platex and uplatex cover different character ranges. On TeX Live 2024, feeding platex a line containing 髙 (U+9AD9, the “ladder” variant of 高) stops with ! LaTeX Error: Unicode character ^^e9^^ab^^99 (U+9AD9) not set up for use with LaTeX., while uplatex compiles the same line without a warning. So if a document fails only at personal names or variant glyphs, suspect the engine rather than the font.

If the characters do appear but come out as tofu boxes or in the wrong typeface, the problem is the Japanese font configuration. On the dvipdfmx route, kanji-config-updmap chooses which Japanese font is embedded; under LuaTeX-ja you name it with \setmainjfont and its siblings. And when the text is garbled only on the machine you sent it to, suspect the encoding and the line endings: if any file was saved as something other than UTF-8 — Shift_JIS or EUC-JP — platex interprets it differently depending on the -kanji= setting. The typesetting methods themselves belong to the Japanese typesetting page, and encoding and line endings to the encoding page.

Why the journal says the fonts are not embedded

Check with pdffonts rather than guessing. Run it over a plain pdfLaTeX output built on TeX Live 2024 and you get columns headed emb, sub, uni, with a row such as KJJYRX+CMR10 Type 1 Builtin yes yes yes — yes under emb, and a six-letter subset prefix in front of the font name. Those two signs together mean the font is embedded. A row with no under emb, on the other hand, will stop a journal’s submission system or a PDF/A check every time. Three causes account for nearly all of them: Type 3 bitmap fonts (no Type1 was installed, so METAFONT bitmaps were used), the fourteen standard PDF base fonts (Helvetica and friends, referenced without being supplied), and a dvipdfmx map pointing at a font that may not be embedded.

$ pdffonts document.pdf
name                       type       encoding  emb sub uni object ID
-------------------------- ---------- --------- --- --- --- ---------
KJJYRX+CMR10               Type 1     Builtin   yes yes yes      4  0

# "yes" under emb, plus the six-letter subset prefix, means embedded.
# Any line with "no" under emb will fail a PDF/A or journal check.

Which page answers which error message

None of the questions above has a single error message attached. When a line does begin with !, the situation is different: the message itself decides where to look. The errors section of this site keeps one page per message, and ! Missing $ inserted., ! Undefined control sequence., ! LaTeX Error: Missing \begin{document}., Runaway argument?, ! LaTeX Error: Option clash for package ... and Overfull \hbox each have their own. The table below gives the wording exactly as reproduced on TeX Live 2024, and what that one line is really telling you. There is only one trick to reading them: fix the topmost error first. TeX errors cascade, and the ones further down are usually aftershocks of the first.