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?

  • 1
    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! 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/… ? Aug 22 '10 at 14:44
  • 1
    @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
  • 1
    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. May 9 '12 at 15:31
  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.

  • 2
    In general, binary search is powerful. Remove approx. half of your document, see if the error disappears or remains, branch and repeat. Aug 22 '10 at 21:48

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.

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.