Debugging Sumatra

Help us debug Sumatra hangs or crashes

If Sumatra crashes or hangs reliably on your machine but we can’t reproduce it ourselves, you can help us by debugging it. Here’s a tutorial on how to do it.

Please first test with the latest pre-release version from https://www.sumatrapdfreader.org/prerelease.html.

Some bugs might already be fixed there.

These instructions require SumatraPDF 3.2 or later.

Getting logs #

We log information that might be helpful in diagnosing issues.

To see the logs, open the Command Palette with Ctrl + K and type show log.

This saves the logs to a file and opens it in the default editor for .txt files.

Install necessary software #

Install the WinDbg debugger from the Microsoft Store. Alternatively, follow Microsoft’s debugger installation instructions.
In SumatraPDF, use the Debug / Download Symbols menu. Symbols are important because they let debuggers such as WinDbg resolve addresses to names.

First, vocabulary. %ProgramFiles% means the standard directory where Windows installs programs. It’s c:\Program Files on 32-bit Windows and c:\Program Files (x86) on 64-bit Windows.

Debugging a crash #

To debug crashes:

start SumatraPDF.exe under the control of WinDBG
- start WinDBG.exe
- File/Open (Ctrl-E), find and open SumatraPDF.exe executable
- In WinDBG, type:
  - .sympath+ SRV*c:\symbols*https://msdl.microsoft.com/download/symbols
  - g
when Sumatra crashes, type: !analyze -v and paste the result of that to the bug report

Debugging a hang #

Here are the steps to follow if Sumatra hangs:

Start SumatraPDF.exe and get it to hang
Start WinDbg.exe
Use File / Attach to Process (F6) and select SumatraPDF.exe from the list
In WinDbg, type:
- .sympath+ SRV*c:\symbols*https://msdl.microsoft.com/download/symbols
- ~*kb
- lmf

Attach the output to the bug report.

SumatraPDF documentation

Debugging Sumatra