One of the most annoying things about LaTeX is that handling errors can be cumbersome and nerve-racking. In fact, it is the main reason that keeps me from actively recommending LaTeX to most people (not only Apple users). Handling LaTeX errors is not something for the average user.

The main reason for this, I believe, is that error messages tend to be cryptic and often outright misleading. The 'crypticness' problem can be solved by learning their basic structure. But the 'missleadingness' is a real problem.

For example, yesterday I struggled for more than an hour with a variety of error messages from biber such as this one:

Entity: line 2004: parser error : Extra content at the end of the document <bcf:citekey order="31">AuthorYear</bcf:citekey> ^

And from pdflatex, such as this one:

! pdfTeX error (font expansion): auto expansion is only possible with scalable 
\@EveryShipout@Output ...@Org@Shipout \box \@cclv 


But my question here does not concern these errors in particular. They are just illustrations for just how misleading these error descriptions can be. Because the problem that cause all this was simply that I had written

\textsf{bla bla bla}

instead of

\enquote{bla bla bla}

And I might add: that mistake was in line 918, so even the line numbers indicated in these error messages are rather far off (ok, biber is not referring to the .tex-file, but I had to learn that too).

I leave it to the geeks to figure out the logic that led to these error messages (cause I'm sure there is a (hidden) logic. But for those who wonder how on earth I could confuse \textsf with \enquote: the answer is: I did not type it, I used the (wrong) keyboard shortcut.

Now, call me stupid or whatever. This is just an example.

My point is: what strategies are there to systematically track down the source of errors when compiling a LaTeX document in an efficient way?

And let me add a more specific version of that question: Assuming that one strategy is to use some sort of version control system to go back to the last error free version of the file and identify the changes that cause the error, is there any automated or semi-automated way to do this. For example, I have my files on dropbox, which allows me to access previous versions of the file up to 30 days back. However, given that a new version is stored every time I hit "save", retrieving each version, saving it, and then loading it into my LaTeX editor to compile it seems rather unfeasible. Not to speak of the problem of relative paths when the old version is not saved in the same folder.

  • 2
    Well the font expansion error is not misleading: One of your font commands (probably the textsf) pointed to a bitmap font which is not scalable and getting rid of such of an error normally involves installation of some fonts. But it is completly impossible for some error recovering strategy to infer from such an error that you actually didn't want to write the (valid) command \textsf. Actually you were quite lucky to get an error which pointed you to the typing error. – Ulrike Fischer Jul 25 '13 at 13:38
  • 2
    @UlrikeFischer OK, so you are suggesting to file that one under "learn your LaTeX basics"? - I'd say that goes far beyond basics. I'd consider myself an advanced LaTeX user (wrote my PhD in LaTeX), but I don't even understand the steps of reasoning that apparently could have brought me closer to the actual typing error. In my mind, it was completely misleading, since I had not fiddled with my microtype settings for months. - Yes, I agree: finding errors is easier if you know LaTeX in an out. But what if you don't? – Christoph Jul 25 '13 at 15:21
  • 1
    No I'm filing this error under "you need your brain and luck". You need to change your point of view and realize that the question is not "how to I get rid of an font error" but "how can I get rid of whatever triggered the use the problematic font?". And then you need to find a answer to the second problem which is much more difficult than the first as fonts are called all over a document. And if you don't find the answer: Ask someone else. That's what I do when I don't find a solution. – Ulrike Fischer Jul 25 '13 at 15:43
  • 1
    Re: finding the "last good/first bad" version, I can add only two words: git bisect... – mbork Mar 15 '14 at 12:36

I'm not sure you want to read this ...

Only the first error LaTeX throws is important because the first error very often causes following errors which vanish after you corrected the first one.

So if you have to find errors

  • write only small parts of your code without compiling!
  • compile,
  • look only for the first error (usually located in the small part of new code),
  • find it (okay, that could be a hard job, but you will be better with more experience) and
  • correct it. Ignore the other errors. Now
  • compile again (and you will have usually not only one error less),
  • look only for the first error,
  • ...

I am used to compile each time I am thinking about my next paragraph to write. So I have only a few lines with new code and be able to locate errors faster.

If you have a lot of code to correct insert after some lines \end{document}, compile and check the errors. If everything is okay, move \end{document} some lines down, recompile and so on.

As @HaraldHanche-Olsen said in his comment:

"If you suspect your error can be anywhere inside a large-ish block of code, performing a binary search is often useful. With the \end{document} trick, instead of moving \end{document} by a few lines at a time, try putting it roughly halfway between the location which produces the error and one that doesn't.

I often comment out a block using \iffalse\fi instead. Of course, with this technique, you must take care not to include part of an environment."

If you are using \input{...} or \include{...} in your document check with commenting it if it includes error(s). If yes, you can use macro \endinput to archive the similar effect to \end{document} (See comment from @JuanA.Navarro).

If you need to use a version control for your TeX file please use a real system to use different versions like svn (subversion) ... Search this website for svn.

  • 13
    I concur with the "compile often" philosophy – Steven B. Segletes Jul 25 '13 at 11:25
  • i have stuff on finding errors, in the uk faq; amusingly, your two examples arise from parts of the system i've never exercised ... without people offering "answers", i generally just plod on with things i understand (or at least know!). – wasteofspace Jul 25 '13 at 11:34
  • 6
    If you suspect your error can be anywhere inside a large-ish block of code, performing a binary search is often useful. With the \end{document} trick, instead of moving \end{document} by a few lines at a time, try putting it roughly halfway between the location which produces the error and one that doesn't. I often comment out a block using \iffalse\fi instead. Of course, with this technique, you must take care not to include part of an environment. – Harald Hanche-Olsen Jul 25 '13 at 11:36
  • 7
    @Kurt I'd like to stubbornly refuse, if I may, to "compile each time I am thinking about my next paragraph" or even to compile often. One of the reasons I'm using LaTeX is because it separates the writing from the formatting (i.e. compiling). While I write, I want to focus on what I write and not be interrupted by technical problems. For this reason, I sometimes do not compile for days. I see your point, but I'd like to push for a solution that takes the problem of finding an error in large amounts of code as given rather than circumventing it. – Christoph Jul 25 '13 at 15:03
  • 1
    @Christoph As a programmer, I find that perspective appalling. Sure, there are cases where you can't always compile because you know you'll get an error anyway as your "code" is incomplete, but waiting a very long time to compile is an easy way to get a huge list of error messages that you then have to go through and resolve all at once rather than resolving as you go along, regardless of how simple it may be to identify and fix the causes. – JAB May 6 '16 at 18:34
  1. Many editors can be convinced to jump automagically to the first error.
  2. If you don't understand the error message, just google it; at least, that's what I do.
  3. Quite often an error in the preamble causes a first error somewhere in the text. Examples: error within code to define a heading will show up after first pagebreake, error in code to change the section will often not be shown before the first section in the text occures. So if you stumble upon an unrelated error message, look whether around the line of the text which the error message provides a special element has been used, maybe for the first time. Go to its definitions in the preamble and search there.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.