Debugging with DAP

There comes a point in every developer's journey where print statements stop being enough. When you need to pause execution, inspect variables at a specific moment, or step through a complex code path line by line, a real debugger is indispensable. The Debug Adapter Protocol brings that full debugging experience into Neovim, so you no longer have to leave your editor or fall back to a separate IDE when things get complicated.

The Debug Adapter Protocol (DAP) brings IDE-level debugging to Neovim -- breakpoints, stepping through code, inspecting variables, and more. Like LSP standardizes language features (see LSP -- Language Server Protocol), DAP standardizes debugging.

What you'll learn in this chapter:

• Understand the Debug Adapter Protocol and how it connects Neovim to language-specific debuggers

• Install and configure nvim-dap with Mason for automatic debug adapter management

• Set breakpoints, step through code, and inspect variables using the DAP UI

• Configure language-specific debug adapters for Python, Go, and JavaScript/TypeScript

• Use the REPL and watch expressions to evaluate code during a debugging session

What is DAP?

┌──────────┐         ┌───────────────────┐
│  Neovim  │ ◄─DAP─► │  Debug Adapter    │
│ (client) │         │  (debugpy, delve, │
│          │         │   node-debug, etc.)│
└──────────┘         └───────────────────┘

DAP provides:

• Breakpoints — pause execution at specific lines

• Step controls — step over, step into, step out, continue

• Variable inspection — see local and global variables

• Watch expressions — monitor specific expressions

• Call stack — see the function call hierarchy

• REPL — evaluate expressions during debugging

Setup

The DAP configuration below uses Lua (see Neovim with Lua for Lua configuration basics) and Mason for automatic adapter installation.

-- lua/plugins/debug.lua
return {
    {
        'mfussenegger/nvim-dap',
        dependencies = {
            -- UI for DAP
            {
                'rcarriga/nvim-dap-ui',
                dependencies = { 'nvim-neotest/nvim-nio' },
                config = function()
                    local dap = require('dap')
                    local dapui = require('dapui')
                    dapui.setup()

                    -- Automatically open/close UI
                    dap.listeners.after.event_initialized['dapui_config'] = function()
                        dapui.open()
                    end
                    dap.listeners.before.event_terminated['dapui_config'] = function()
                        dapui.close()
                    end
                    dap.listeners.before.event_exited['dapui_config'] = function()
                        dapui.close()
                    end
                end,
            },
            -- Virtual text for variables
            { 'theHamsta/nvim-dap-virtual-text', opts = {} },
            -- Mason integration
            'williamboman/mason.nvim',
            'jay-babu/mason-nvim-dap.nvim',
        },
        keys = {
            { '<F5>', function() require('dap').continue() end, desc = 'Debug: Continue' },
            { '<F10>', function() require('dap').step_over() end, desc = 'Debug: Step Over' },
            { '<F11>', function() require('dap').step_into() end, desc = 'Debug: Step Into' },
            { '<F12>', function() require('dap').step_out() end, desc = 'Debug: Step Out' },
            { '<leader>db', function() require('dap').toggle_breakpoint() end, desc = 'Toggle breakpoint' },
            { '<leader>dB', function()
                require('dap').set_breakpoint(vim.fn.input('Breakpoint condition: '))
            end, desc = 'Conditional breakpoint' },
            { '<leader>dr', function() require('dap').repl.open() end, desc = 'Debug REPL' },
            { '<leader>dl', function() require('dap').run_last() end, desc = 'Re-run last debug' },
            { '<leader>du', function() require('dapui').toggle() end, desc = 'Toggle debug UI' },
        },
        config = function()
            -- Install debug adapters with Mason
            require('mason-nvim-dap').setup({
                ensure_installed = {
                    'python',       -- debugpy
                    'delve',        -- Go
                    'js',           -- js-debug-adapter
                },
                automatic_installation = true,
            })
        end,
    },
}

Language-Specific Configuration

Python

local dap = require('dap')

dap.adapters.python = {
    type = 'executable',
    command = 'python',
    args = { '-m', 'debugpy.adapter' },
}

dap.configurations.python = {
    {
        type = 'python',
        request = 'launch',
        name = 'Launch file',
        program = '${file}',
        pythonPath = function()
            -- Use virtual environment if available
            local venv = os.getenv('VIRTUAL_ENV')
            if venv then
                return venv .. '/bin/python'
            end
            return '/usr/bin/python3'
        end,
    },
}

Go

dap.adapters.delve = {
    type = 'server',
    port = '${port}',
    executable = {
        command = 'dlv',
        args = { 'dap', '-l', '127.0.0.1:${port}' },
    },
}

dap.configurations.go = {
    {
        type = 'delve',
        name = 'Debug',
        request = 'launch',
        program = '${file}',
    },
    {
        type = 'delve',
        name = 'Debug test',
        request = 'launch',
        mode = 'test',
        program = '${file}',
    },
}

JavaScript / TypeScript

dap.adapters['pwa-node'] = {
    type = 'server',
    host = 'localhost',
    port = '${port}',
    executable = {
        command = 'node',
        args = {
            require('mason-registry').get_package('js-debug-adapter'):get_install_path()
            .. '/js-debug/src/dapDebugServer.js',
            '${port}',
        },
    },
}

dap.configurations.javascript = {
    {
        type = 'pwa-node',
        request = 'launch',
        name = 'Launch file',
        program = '${file}',
        cwd = '${workspaceFolder}',
    },
}
dap.configurations.typescript = dap.configurations.javascript

DAP Keybindings Reference

Key	Action
F5	Start / Continue
F10	Step Over
F11	Step Into
F12	Step Out
<leader>db	Toggle breakpoint
<leader>dB	Conditional breakpoint
<leader>dr	Open REPL
<leader>du	Toggle debug UI
<leader>dl	Re-run last debug session

Debug UI Layout

When debugging, nvim-dap-ui opens panels showing:

┌─────────────┬──────────────────┬────────────┐
│ Variables   │   Source Code    │ Breakpoints│
│             │                  │            │
│ > local_var │   5: function()  │ file:5     │
│ > table     │ ► 6:   print()  │ file:12    │
│             │   7: end         │            │
├─────────────┴──────────────────┴────────────┤
│ REPL / Console                              │
│ > print(variable)                           │
│ "value"                                     │
└─────────────────────────────────────────────┘

Tip: Install nvim-dap-virtual-text to see variable values inline next to the code as you debug.

Summary

The Debug Adapter Protocol brings full-featured debugging to Neovim, letting you set breakpoints, step through execution, inspect variables, and evaluate expressions without switching to a separate IDE. With nvim-dap, nvim-dap-ui, and Mason handling adapter installation, you get a portable debugging setup that works across Python, Go, JavaScript, and many other languages.

Key takeaways:

• DAP is to debugging what LSP is to language features: a protocol that standardizes communication between Neovim and language-specific debug adapters.

• nvim-dap-ui automatically opens and closes debug panels (variables, breakpoints, REPL, call stack) when a debug session starts and stops.

• Mason can automatically install debug adapters (debugpy, delve, js-debug-adapter), eliminating manual setup.

• The function keys (F5, F10, F11, F12) provide familiar step controls, while <leader>db toggles breakpoints at the current line.

Exercises

1. Set a breakpoint and start debugging -- Open a simple script in a supported language, set a breakpoint on a line of interest, and start a debug session.

2. Step through code execution -- With a debug session paused at a breakpoint, practice stepping over, into, and out of function calls.

3. Inspect variables and evaluate expressions -- During a paused debug session, examine local variables in the DAP UI and use the REPL to evaluate custom expressions.

4. Set a conditional breakpoint -- Set a breakpoint that only pauses execution when a specific condition is met, such as a variable reaching a certain value.

5. Re-run the last debug session -- After completing a debug session, quickly re-launch it with the same configuration without re-selecting options.