hyperref incorrect links: how to debug?

Question

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?

Answer 1

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.

Answer 2

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.