debug-crash-dump

Crash Dump Debugging

Download and analyze crash dumps from CI workflow failures (especially fault_injection_full).

See docs/CrashDumpDebugging.md for the full human-readable guide.

When to Use

• User asks to debug a CI crash or test failure with a crash dump
• User asks to download crash dump artifacts from a workflow run
• User asks to set up CDB, WinDbg, or mcp-windbg
• User asks to analyze a .dmp file
• User asks about fault injection leak detection failures

Agent Prerequisites

1. Windows Debugging Tools (CDB/WinDbg) — Install the Debugging Tools feature from the Windows SDK:

   # Download the SDK online installer
   Invoke-WebRequest -Uri "https://go.microsoft.com/fwlink/?linkid=2272610" -OutFile winsdksetup.exe
   # Install only the debugging tools (elevated)
   Start-Process -FilePath .\winsdksetup.exe -ArgumentList "/features","OptionId.WindowsDesktopDebuggers","/quiet","/norestart" -Verb RunAs -Wait
   

   CDB installs to: C:\Program Files (x86)\Windows Kits\10\Debuggers\x64\cdb.exe

2. mcp-windbg (MCP server for AI-assisted dump analysis):

   # Install Python 3.12 via NuGet (if not already available)
   nuget install python -Version 3.12.8 -OutputDirectory C:\Users\$env:USERNAME\tools
   $pyExe = (Get-ChildItem "C:\Users\$env:USERNAME\tools\python.3.12.8" -Recurse -Filter "python.exe" | Select-Object -First 1).FullName
   & $pyExe -m ensurepip --upgrade
   & $pyExe -m pip install mcp-windbg
   

Downloading Artifacts

# Download crash dumps and build artifacts (PDBs) from a CI run
gh run download <run_id> -R <owner>/ebpf-for-windows -n "Crash-Dumps-<test>-x64-<config>" -D crash-dumps
gh run download <run_id> -R <owner>/ebpf-for-windows -n "Build-x64-<config>" -D build
# Extract inner build zip for PDBs (produces build\<config>\<config>\ with PDBs)
Expand-Archive build\build-<config>.zip -DestinationPath build\<config>

Analyzing Dumps with CDB

$cdbPath = "C:\Program Files (x86)\Windows Kits\10\Debuggers\x64\cdb.exe"
$symPath = "build\<config>\<config>;SRV*C:\Symbols*https://msdl.microsoft.com/download/symbols"

# Quick triage: exception record + stack trace
& $cdbPath -z crash-dumps\unit_tests.exe.XXXX.dmp -y $symPath -lines -c ".ecxr;kP;q"

# Full automated analysis
& $cdbPath -z crash-dumps\unit_tests.exe.XXXX.dmp -y $symPath -c "!analyze -v;q"

Running mcp-windbg Server

$pyExe = (Get-ChildItem "C:\Users\$env:USERNAME\tools\python.3.12.8" -Recurse -Filter "python.exe" | Select-Object -First 1).FullName
$cdbPath = "C:\Program Files (x86)\Windows Kits\10\Debuggers\x64\cdb.exe"
$symPath = "build\<config>\<config>;SRV*C:\Symbols*https://msdl.microsoft.com/download/symbols"

& $pyExe -m mcp_windbg --cdb-path $cdbPath --symbols-path $symPath --transport streamable-http --port 8765
# MCP endpoint: http://127.0.0.1:8765/mcp

Common Patterns

• Fault injection crashes: Usually assert _allocations.empty() in leak_detector.cpp — a memory leak detected during teardown. Check the leak detector's _in_memory_log for the allocation call stack:

  $$ Get exception context and inspect the stack to find the leak_detector frame:
  .ecxr
  kP
  $$ Identify the frame index where 'this' is the leak_detector instance
  .frame <N>
  dx this->_in_memory_log
  

• Crash dump artifacts: Named Crash-Dumps-<test_name>-<platform>-<config> (e.g., Crash-Dumps-fault_injection_full-x64-Debug)
• Build artifacts with PDBs: Named <build_artifact>-<config> (for the default build_artifact=Build-x64, this is Build-x64-Debug), and contain an inner zip build-<config>.zip