FAQ

Algunos problemas de LaTeX se anuncian con una línea que empieza por !. Los caros, no. Una referencia que sigue en ?? por muchas veces que se compile; una figura que aterriza dos páginas más tarde; un PDF en A4 cuando la fuente decía letterpaper; un manuscrito que compila aquí y falla en la máquina del coautor. Estas preguntas frecuentes reúnen solo esas cuestiones transversales —las que ponen en juego varios mecanismos a la vez— y responden a cada una describiendo lo que ocurre de verdad durante la ejecución. Los problemas que zanja un único mensaje de error tienen su propia página; el índice del final lleva hasta ellas.

Por qué hay que compilar dos veces

Porque LaTeX lee la fuente de principio a fin una sola vez y no puede mirar hacia adelante. Al componer \ref{sec:first} en la página 1, el número que acabará teniendo \label todavía no se conoce. Por eso \label escribe ese número en el archivo .aux y \ref lee la .aux que dejó la ejecución anterior. Medido en TeX Live 2024, la primera pasada imprime LaTeX Warning: Reference 'sec:first' on page 1 undefined on input line 4. y LaTeX Warning: There were undefined references., y el PDF dice realmente «See Section ?? on page ??.» La .aux contiene en ese momento \newlabel{sec:first}{{1}{1}{}{}{}}, que la segunda pasada recoge para producir «See Section 1 on page 1.» Un ?? no es una avería: avisa de que se está todavía en la primera vuelta.

$ 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.

La advertencia que cierra la ejecución —LaTeX Warning: Label(s) may have changed. Rerun to get cross-references right.— es el propio LaTeX informando de que la .aux recién escrita difiere de la que leyó. Lo importante es que dos pasadas son un mínimo, no una regla. Un dígito de más puede reajustar una línea, lo que cambia un número de página y con él la .aux; con índice general, índice de figuras o marcadores de hyperref en juego, tres o cuatro pasadas son de lo más corriente. latexmk existe justo para esto: repite hasta que la .aux deja de cambiar. Conviene, pues, dejarle la iteración. A la inversa, no persiga nunca un ?? sin haber compilado dos veces. Si sobrevive a dos pasadas, el \label está mal escrito, no existe, o estorba una .aux obsoleta: borrarla devuelve todo a la primera pasada.

Por qué la bibliografía no aparece

Porque la bibliografía la genera un programa aparte, externo a LaTeX, y un ciclo completo exige cuatro órdenes. bibtex no lee nunca el .tex. Lee las líneas \citation y \bibdata que LaTeX escribió en la .aux, extrae del .bib las entradas correspondientes y produce un .bbl. Medidas en TeX Live 2024, las etapas son inconfundibles. El primer pdflatex imprime LaTeX Warning: Citation 'knuth1984' on page 1 undefined y el PDF dice «As shown by [?].» sin lista alguna. Al ejecutar bibtex, este declara sus entradas: The top-level auxiliary file: doc.aux, The style file: plain.bst, Database file #1: refs.bib. El segundo pdflatex sí compone la lista References, pero la llamada de cita sigue en [?]. Solo la tercera pasada la convierte en [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

La tercera pasada se explica por el mismo viaje de ida y vuelta por la .aux. Los \bibitem del .bbl que lee la segunda pasada escriben en la .aux la correspondencia «esta clave vale [1]», pero lo hacen a mitad de esa misma pasada, cuando el \cite del cuerpo ya está compuesto. La correspondencia solo sirve, pues, a partir de la ejecución siguiente, de ahí que haga falta un tercer pdflatex, la cuarta orden en total. biblatex con biber tiene la misma forma; biber sustituye a bibtex y lee un .bcf. En la práctica conviene entregarlo todo a latexmk y dejar de contar. Si la lista sigue vacía, la causa es casi siempre una de tres: \bibliography{refs} escrito con la extensión .bib, ningún \cite en el cuerpo (con \nocite{*} aparece todo) o una clave mal tecleada. Lo último se ve en el registro .blg: Warning--I didn't find a database entry for "...".

Por qué la figura acaba en la página equivocada

Porque un figure es un flotante: LaTeX lo retiene hasta que una página le deja sitio. El punto donde más gente tropieza es la diferencia entre \newpage y \clearpage. \newpage se limita a terminar la página actual: no vacía la cola de flotantes pendientes. \clearpage compone antes todos los flotantes en espera y solo después cierra la página. Al compilar en TeX Live 2024 dos versiones de una misma fuente que difieren únicamente en esa orden, y leer el resultado página a página con pdftotext, la consecuencia es inequívoca.

\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.

La versión con \newpage salió de cuatro páginas: p. 1 el cuerpo de Alpha, p. 2 el título «Beta» y su texto, p. 3 la figura 1, p. 4 la figura 2. La figura 1, que pertenece a Alpha, saltó por encima del título de la sección siguiente y apareció detrás. La versión con \clearpage tiene tres páginas: p. 1 el cuerpo de Alpha, p. 2 solo la figura 1, p. 3 la figura 2 junto con el título «Beta» y su texto. La figura ya no cruza la frontera de sección y el documento pierde además una página. La mayoría de los casos de «mi figura acabó en el capítulo equivocado» se remontan, pues, a un \newpage colocado en una ruptura estructural. En rupturas de capítulo y sección conviene \clearpage (\cleardoublepage si se imprime a doble cara). Además, escriba [htbp] y no un [h] suelto: [h] significa «aquí si cabe, si no más tarde», y un flotante más alto que \textheight jamás compartirá página con texto. El control fino de los flotantes corresponde a la página de flotantes y colocación.

Por qué la imagen no aparece, o sale como un recuadro vacío

Si no aparece nada, sospeche de un desajuste entre el formato de la imagen y la ruta de salida; si aparece un recuadro vacío, sospeche de draft. pdflatex lee directamente PDF, PNG y JPEG y no lee EPS en absoluto: hay que convertirlo con epstopdf o dejarlo en manos del paquete epstopdf. La ruta DVI, platex y luego dvipdfmx, sí admite EPS. Cuando el archivo no aparece, el mensaje es ! LaTeX Error: File 'fig.eps' not found., y la causa es casi siempre una extensión olvidada, una ruta equivocada o un \graphicspath{{figures/}} sin su barra final. El otro clásico, ! LaTeX Error: Cannot determine size of graphic in xxx.png (no BoundingBox)., surge cuando a graphicx nunca se le dijo bajo qué controlador se ejecuta; la propia FAQ de Cloud LaTeX dedica a ese único mensaje una entrada aparte.

El caso del recuadro vacío resulta casi decepcionante de simple una vez entendido. Un documento compilado en TeX Live 2024 con \documentclass[draft]{article} y releído con pdftotext devuelve el nombre del archivo como texto allí donde debería estar la imagen. Eso es exactamente lo que hace draft: se salta el dibujado y deja un recuadro de las mismas dimensiones con el nombre dentro. Olvidar un draft en las opciones de clase y concluir después que las imágenes están dañadas es uno de los accidentes más frecuentes. Para la versión de entrega hay que quitar draft; si solo se busca velocidad, \usepackage[draft]{graphicx} limita el efecto a las ilustraciones. Y si la figura sigue ausente tras descartar todas las causas de esta sección, quizá no falte: puede haber flotado a otra página. Vuelva a la sección anterior.

Por qué compila en mi máquina y no en la del coautor

Las diferencias entre dos máquinas se reducen en la práctica a tres cosas: el año de TeX Live, las versiones de los paquetes instalados y los archivos propios guardados en el árbol personal. Las dos primeras se ven con una sola línea. Poner \listfiles antes de \documentclass hace que la .log termine con un bloque *File List* con una línea por archivo, con fecha y versión: en TeX Live 2024, entradas como amsmath.sty 2023/05/13 v2.17o AMS math features o graphicx.sty 2021/09/16 v1.2d Enhanced LaTeX Graphics. Pida al coautor el mismo bloque, compare ambos y el culpable suele caber en una línea. La añada del motor la da pdflatex --version, que responde 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)

La tercera causa, el árbol personal, es la más difícil de detectar. kpsewhich -var-value=TEXMFHOME devuelve, en TeX Live 2024 sobre macOS, /Users/you/Library/texmf: el texmf.cnf que acompaña a TeX Live 2024 fija TEXMFHOME = ~/Library/texmf, mientras que en Windows y Linux el valor por omisión es ~/texmf. Cualquier .sty, .bst o tipografía privada que resida allí es visible solo en su máquina, de modo que quien reciba el manuscrito obtiene ! LaTeX Error: File 'mystyle.sty' not found. El remedio es directo: guarde los archivos caseros en la carpeta del manuscrito y entréguelos con él. Si además quiere borrar la diferencia de año de TeX Live, fije el entorno mismo con algo como una imagen de Docker. Los usos de la coautoría corresponden a la página de colaboración, y la fijación del entorno a la de Docker y CI.

Por qué el PDF sale en A4 si la fuente pedía letterpaper

Porque una opción de clase cambia la mancha —el bloque de texto y sus márgenes—, no el papel del PDF. Al compilar tal cual \documentclass[letterpaper]{article} en TeX Live 2024 y consultar pdfinfo, la respuesta es Page size: 595.276 x 841.89 pts (A4). La razón está en la configuración de arranque de pdfTeX. El pdftexconfig.tex grabado en el formato fija \pdfpageheight = 297 true mm y \pdfpagewidth = 210 true mm, dos primitivas que determinan la caja de medios del PDF. Una opción de clase no llega a esa capa. Añada \usepackage[letterpaper]{geometry} al mismo documento y la respuesta pasa a 612 x 792 pts (letter), porque geometry se ocupa a la vez de la mancha y del tamaño de la hoja.

$ 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)

Hay tres remedios y la situación elige uno. El más directo es geometry, que además permite fijar los márgenes en el mismo sitio. Si no se quiere engordar el preámbulo, escribir antes de \documentclass la línea \pdfpagewidth=8.5truein \pdfpageheight=11truein da igualmente 612 x 792 pts (letter) —medido—. En la ruta DVI es dvipdfmx quien fabrica el PDF, así que el tamaño se indica en la conversión, por ejemplo con dvipdfmx -p letter. Conviene saber por qué esas longitudes llevan true: cuando el documento entero se escala con \mag, solo las dimensiones marcadas con true quedan a salvo del escalado. Los detalles del papel corresponden a la página sobre la producción de PDF.

Por qué el japonés no aparece o sale corrupto

Casi siempre es el motor equivocado o la codificación equivocada del archivo. pdflatex no compone japonés en absoluto. Hay dos rutas viables: uplatex (con una clase jsarticle o jlreq) pasando el testigo a dvipdfmx, o lualatex con luatexja. La fuente se guarda en UTF-8. Lo que se pasa por alto es que «admite japonés» no es una sola cosa: platex y uplatex cubren rangos de caracteres distintos. En TeX Live 2024, una línea que contiene 髙 (U+9AD9) detiene a platex con ! LaTeX Error: Unicode character ^^e9^^ab^^99 (U+9AD9) not set up for use with LaTeX., mientras que uplatex compila la misma línea sin una sola advertencia. Así que, si un documento falla solo en nombres propios o glifos variantes, sospeche del motor y no de la tipografía.

Si los caracteres sí aparecen pero salen como cuadros de sustitución o en otra tipografía, el problema es la configuración de fuentes japonesas. En la ruta dvipdfmx, kanji-config-updmap elige qué fuente japonesa se incrusta; bajo LuaTeX-ja se nombra con \setmainjfont y análogos. Y si el texto solo se corrompe en la máquina del destinatario, sospeche de la codificación y de los finales de línea: en cuanto un archivo se guarda en algo que no sea UTF-8 —Shift_JIS o EUC-JP—, platex lo interpreta de otro modo según el ajuste -kanji=. Los métodos de composición corresponden a la página de composición japonesa, y la codificación y los saltos de línea a la página de codificación.

Por qué dicen que las fuentes no están incrustadas

Se comprueba con pdffonts, no se adivina. Aplicado a una salida pdfLaTeX corriente producida en TeX Live 2024, muestra las columnas emb, sub, uni y una fila como KJJYRX+CMR10 Type 1 Builtin yes yes yes: yes bajo emb y un prefijo de subconjunto de seis letras delante del nombre. Ambas señales juntas significan que está incrustada. Una fila con no bajo emb, en cambio, detendrá sin falta el sistema de envío de una revista o una comprobación PDF/A. Tres causas cubren casi todos los casos: fuentes de mapa de bits Type 3 (a falta de una Type1 instalada se usaron mapas de bits de METAFONT), las catorce fuentes base del PDF (Helvetica y compañía, referenciadas sin suministrarse) y un mapa de dvipdfmx que apunta a una fuente no incrustable.

$ 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.

Qué página responde a qué mensaje de error

Ninguna de las preguntas anteriores depende de un único mensaje de error. Cuando una línea sí empieza por !, la cosa cambia: el mensaje mismo decide dónde mirar. La sección de errores de este sitio dedica una página a cada mensaje, y ! Missing $ inserted., ! Undefined control sequence., ! LaTeX Error: Missing \begin{document}., Runaway argument?, ! LaTeX Error: Option clash for package ... y Overfull \hbox tienen la suya. La tabla siguiente recoge el texto tal como se reprodujo en TeX Live 2024 y lo que esa única línea está diciendo en realidad. Solo hay un truco de lectura: corrija primero el error más alto. Los errores de TeX se encadenan y los de más abajo suelen ser réplicas del primero.