How to debug the debugger

This page describes how to debug the jupyter extension and debugpy when the user is running a 'debug' command. You should probably read all of the debug topics to familiarize yourself with how debugging works before following the steps below.

Debugging Extension side code

When the user clicks Debug Cell in a notebook, there are a number of entrypoints (as shown in the sequence diagram on the other wiki page)

You can debug these entry points just like debugging anything in the extension:

• Set a breakpoint
• Launch 'Extension' debugger launch.json entry.
• Perform the user task to start debugging

Entry Point	Why you might start here	What the cause might be
Debugging Manager::startDebuggingConfig	Debug cell isn't starting the debugger. This is the main entrypoint and it's what tells VS code to start the debugger	Debug config may not match, so check the config when starting.
Kernel Debug Adapter::handleMessage	Debug cell is starting the debugger (or entering debug mode) but breakpoints don't hit or the cell never looks like it's running.	The correct DAP messages are note being sent to the kernel.
Kernel Debug Adapter::onIOPubMessage	Debug cell is starting the debugger (or entering debug mode) but breakpoints don't hit or the cell never looks like it's running.	The resulting DAP messages from the debugpy are referencing invalid paths or showing an error.
Kernel Debug Adapter::dumpCell	Debug cell is starting the debugger and cell seems to run, but breakpoints don't bind or seem to jump around	dumpCell may be creating output files not referencable by VS code (like remote paths) or line number translation could be off
Kernel Debug Adapter::translate functions	Breakpoints move or don't bind. Wrong files open when stopping	File path translation is generating invalid paths for debugpy or there's a line number translation problem

Debugging Debugpy

Okay so what if all of those entry points look good but debugpy just doesn't seem to respond correctly?

There are three things you can do to debug debugpy:

Turn on logging

Debug debugpy's

• Maybe have to debug VS code itself
• Where to put breakpoints there
• Debug debugpy
• Turn on logging
• Attach to the listener process (using another instance)
• pydevd is all logging (replace code in _vendored)