Haskell Debugging

Haskell Debugging

Two complementary approaches: the GHCi built-in debugger (fast, terminal-based, no setup beyond GHCi) and DAP adapters (integrated into VS Code and other editors with a GUI).

GHCi debugger

The GHCi debugger is always available — no extra packages. Load your module with cabal repl or ghci, then use these commands:

Setting breakpoints

-- By function name
:break MyModule.myFunction

-- By module and line number
:break MyModule 42

-- List active breakpoints
:show breaks

-- Delete a breakpoint by index (from :show breaks output)
:delete 0

Stepping through execution

-- Run until next breakpoint; starts evaluation
:continue

-- Step into the next redex (one reduction)
:step

-- Step over (run to next line without entering calls)
:steplocal

-- Step to next breakpoint in a specific module
:stepmodule MyModule

Inspecting state at a breakpoint

-- Print a variable (forces evaluation)
:print x

-- Force a thunk and print (like :print but evaluates completely)
:force x

-- Show current locals in scope
:show bindings

-- Evaluate an expression in the current context
x + 1

Tracing (non-interactive)

When you don't want to step but want a call history:

-- Run with tracing enabled; builds a call history
:trace myFunction arg1

-- Show the call history after a breakpoint or exception
:history

-- Show the back trace
:back

Catching exceptions

-- Break on any exception
:set -fbreak-on-exception

-- Break only on errors (not pure exceptions)
:set -fbreak-on-error

-- Disable
:unset -fbreak-on-exception

Practical GHCi debugging workflow

1. cabal repl in your project.
2. :break MyModule.suspectFunction — set a breakpoint.
3. Call the function with test inputs: myFunction testInput.
4. Execution stops at the breakpoint. Use :print, :force, :show bindings.
5. :step to move forward one reduction; :continue to run to the next breakpoint.
6. :delete breakpoints when done; :quit to exit.

The GHCi debugger operates on interpreted code, not compiled code. If a module is compiled (with -O), breakpoints won't fire in it. Use cabal repl which loads library modules interpreted.

DAP (Debug Adapter Protocol)

DAP adapters expose the GHCi debugger as a protocol that editors understand — enabling GUI breakpoints, variable panels, and step buttons. Three packages work together:

Installation

cabal install haskell-dap ghci-dap haskell-debug-adapter

All three must be installed together — they depend on each other's types. They are built against the active GHC, so reinstall them after changing the pinned compiler. They land in cabal's install directory (cabal path --installdir), which must be on PATH.

VS Code configuration

Install the Haskell extension if not already installed. Then add a launch configuration to .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "ghc",
      "request": "launch",
      "name": "Debug Haskell (cabal repl)",
      "ghci": "cabal repl",
      "startup": "test/Spec.hs",
      "stopOnEntry": false,
      "logFile": "/tmp/haskell-debug-adapter.log",
      "logLevel": "WARNING"
    }
  ]
}

Key fields:

• ghci — the command to launch GHCi. Use cabal repl for library/executables, or cabal repl my-package:test:my-test to load a specific test suite.
• startup — a Haskell file to load first. For a library, this is typically your entry module. For a test suite, point at Spec.hs.
• stopOnEntry — set true to pause immediately at the first line; false to run until the first breakpoint.
• logFile — path for adapter debug output. Useful when the debugger fails to start.

Setting breakpoints in VS Code

Once the launch configuration is set:

1. Click the left gutter in any .hs file to set a breakpoint (red dot).
2. Press F5 (or Run → Start Debugging) to launch.
3. VS Code shows locals, call stack, and a watch panel when execution pauses.

Breakpoints set in the editor translate to :break commands sent to ghci-dap.

Debugging a specific test

To debug a failing hspec test rather than the full suite:

{
  "type": "ghc",
  "request": "launch",
  "name": "Debug failing test",
  "ghci": "cabal repl my-project:test:my-project-test",
  "startup": "test/Spec.hs",
  "stopOnEntry": false
}

Set a breakpoint in the function the test exercises, then trigger the test from the GHCi panel: hspec spec.

Troubleshooting DAP

• Adapter doesn't start: check logFile output. The most common cause is haskell-debug-adapter not on PATH — confirm with which haskell-debug-adapter, and check that cabal path --installdir is on PATH in the shell that launches the editor.
• Breakpoint not hit: the module may be compiled rather than interpreted. Check that cabal repl is loading the module as interpreted (no * prefix on the module name in the GHCi prompt means it's compiled).
• Variables show _thunk: the value hasn't been forced yet. Use :force from the debug console, or add ! to the field in your data type.
• DAP hangs on startup: ghci-dap and haskell-debug-adapter versions must be compatible. Reinstall all three together to ensure version alignment.

Choosing between GHCi and DAP

When debugging isn't the right tool

• Type-level bugs: the compiler usually surfaces these at build time. The debugger operates at runtime on evaluated values, not types.
• Performance issues: reach for profiling (-prof -fprof-auto, +RTS -s, ghc-prof-flamegraph) rather than the debugger — see haskell-benchmarking.
• Concurrency bugs: the debugger doesn't handle concurrent execution well. Debug.Trace.traceEventIO with ThreadScope gives better visibility into concurrent behavior.
• Effect handler wiring: if effects aren't resolving correctly, add explicit type annotations and let the compiler guide you — runtime debugging can't surface a missing runMyEffect call in the interpreter stack.

Related

• GHCi :trace and space leaks: haskell-benchmarking for profiling and flame graphs.
• Testing strategies that reduce the need for debugging: haskell-testing.