Take the 2-minute tour ×

Problem Statement. I am writing a large document that is too big to provide here for illustration. For the first hundred pages or so, the hyperlinks are correctly matched to the displayed text. For example, the text might refer to page 55, and the hyperlink would also direct the PDF viewer to that page. But then, at some point, the hyperlinks start pointing to incorrect pages, much earlier in the document. For example, a link might go to page 8, but the displayed text might refer correctly to page 80. (Throughout the document, the displayed references, e.g. page numbers or section numbers, remain correct. It is the hyperlinks that are broken at some point.)

Question. is there a way to debug documents that use the hyperref package, to find out why this sort of thing is happening?

share|improve this question
Dan, I hope some bright spark can help you here. Unfortunately I can't (short of advising you to switch on the verbose option which, given the size of your document, isn't likely to lead anywhere very pretty). However, if your search doesn't turn up many useful answers here, why don't you repeat your question on the comp.text.tex usenet forum? (Hosted on google groups if you can't get to it any other way.) Heiko Oberdiek graciously helps out many people with hyperref problems over there. He's the best person on the planet for this sort of problem, bar none. Be sure to report back here! –  Geoffrey Jones Aug 22 '10 at 13:50
Did you read your log file? Did you get any warnings? In particular, something similar to these: en.wikibooks.org/wiki/LaTeX/… ? –  Jukka Suomela Aug 22 '10 at 14:44
@Jukka: Yes, I've been spending some time grepping in the log file, and reading it (as best I can) to see if there is something along the lines of the wikibooks link that you so kindly posted. I've also been removing text and seeing if I can make the problem go away. (This is, I admit, a very crude technique, but I've been programming since the 1970s and I still return to variants of it!) –  dank Aug 22 '10 at 15:26
My problem seems to have been related to a newtheorem defined in a style file use. Making my own newtheorem fixed the problem. I am adding this note as a "comment", not an "answer", because it does not address the actual question I posed, about debugging problems with hyperref. –  dank Aug 22 '10 at 19:14
@dank: If you were able to resolve this problem, it would be helpful if you posted some details here in case others encounter similar problems. –  Peter Grill May 9 '12 at 15:31
add comment

2 Answers

up vote 2 down vote accepted
  1. Clean Compile (delete all auxiliary files and do the latex-bibtex-latex-latex, etc dance from scratch)
  2. Remove/turn-off as many packages as you can. Some packages may conflict with others
  3. Reduce your document to the smallest sample showing the problem
  4. Google =)
  5. Grep *.log files and run latex interractevly to see if there are problems.

ps. inserting pdfpages can mess-up page number orderring.

share|improve this answer
In general, binary search is powerful. Remove approx. half of your document, see if the error disappears or remains, branch and repeat. –  Jukka Suomela Aug 22 '10 at 21:48
add comment

If you're using git to store your documents, and committing regularly, there is an excellent debugging method using git bisect.

First while viewing the problematic version (ie. newest commit in HEAD), start bisect, and tell it there's a problem:

git bisect start
git bisect bad

Then, use git log and git checkout <commit-hash> to find an old commit that works. Doesn't matter how old, but make sure you compile freshly and check!

Next, use git bisect good to tell git you've found a good version. Git will then check out a version half way between the two. Compile this version. Check if it's good or bad, and tell git appropriately: git bisect [good|bad].

Repeat this last step until git tells you it's found the problematic commit. It'll spit you back out at HEAD, and give you a commit hash, which you can use to see what changed with git show <commit-hash> [file name]. Once you spot the difference you can try reverting it.

If you only notice your problem after making a ton of commits, this can be a real lifesaver.

share|improve this answer
add comment

Your Answer


