netcoredbg-mcp 0.7.0

MCP server for debugging C#/.NET code using netcoredbg

🌐 English | Русский

netcoredbg-mcp

Your AI agent can write .NET code, run tests, even deploy — but when something goes wrong, it's blind. No call stacks. No variable inspection. Can't set breakpoints. Just "it crashed, check the logs."

netcoredbg-mcp turns any AI agent into a capable .NET debugger. Set breakpoints, step through code, inspect variables, take screenshots of WPF windows, evaluate expressions — all through the Model Context Protocol. Zero IDE required.

"Like giving your AI agent a VS Code debugger it can actually use."

66 tools · 7 prompts · 4 resources · 546 tests

Quick Links

• Get Started: Install · Configure · First Debug Session
• Reference: Tools · Resources · Prompts · Architecture
• Guides: GUI App Debugging · Visual Inspection · Troubleshooting

---

What's New in v0.6.0

Released 2026-04-07. Full changelog →

• MCP Progress Notifications — build output streaming, 9-phase start_debug progress, execution heartbeat every 5s
• Git Worktree Support — paths in worktrees auto-detected and accepted (#31)
• Tracepoint Fix — auto-resume now works (excluded tracepoint-owned breakpoints from user bp check)
• mcp-mux Isolation — each CC session gets its own daemon with correct project scope
• 10 Configurable Env Vars — all hardcoded limits now tunable via environment
• 100 Smoke Tests — DataGrid select, tracepoint auto-resume, heartbeat, path validation
• Screenshot 1568px — default max width increased to Claude vision maximum

---

Highlights

Feature	Description
66 MCP Tools	Debug control, breakpoints, inspection, tracepoints, snapshots, output, UI automation, process management
Long-Poll Execution	continue and step_* tools block until stopped — no polling loops
State Machine Responses	Every response includes state, next_actions, message — the agent always knows what to do next
Agent Intelligence	ElementResolver ranked search, ExtractText 5-strategy fallback, CLR type name detection
Client-side Tracepoints	Pause → evaluate → resume without netcoredbg support — rate limited, asyncio-safe
State Snapshots + Diff	Capture variable state at any stop, compare snapshots across sessions (FIFO, max 20)
GUI App Detection	Auto-detects WPF/WinForms/Avalonia from runtimeconfig.json and adjusts workflow hints
Screenshots + Set-of-Mark	See the app UI, get numbered element overlays, click by annotation ID
stepInTargets	Choose which function to step into on multi-call lines
Variable Paging	filter, start, count parameters for navigating large collections
Pre-build	Build before debug with pre_build: true — hidden warnings surfaced via get_build_diagnostics
Smart Resolution	Auto-resolves .exe to .dll for .NET 6+ to avoid deps.json conflicts
Version Check	Detects dbgshim.dll mismatches automatically on session start
Process Reaper	PID file tracking with cleanup_processes — never lose orphan debugger processes
mcp-mux Aware	Session ownership guards for multi-agent safety — first agent claims the debug session, others get a clear error
ToolAnnotations	readOnlyHint, destructiveHint, idempotentHint on every tool for smart agent routing

---

Quick Start (30 seconds)

# 1. Install
pip install netcoredbg-mcp

# 2. Register with Claude Code
claude mcp add --scope user netcoredbg -- netcoredbg-mcp --project-from-cwd

# 3. Debug
# "Set a breakpoint on line 42 of Program.cs and run my app"

---

Critical Notes

[!WARNING] dbgshim.dll Version Compatibility

The dbgshim.dll in your netcoredbg folder MUST match the major version of the .NET runtime you're debugging. This is an undocumented Microsoft requirement. Mismatch causes:

• E_NOINTERFACE (0x80004002) errors
• Empty call stacks
• Failed variable inspection

Target Runtime	Required dbgshim.dll Source
.NET 6.x	C:\Program Files\dotnet\shared\Microsoft.NETCore.App\6.0.x\dbgshim.dll
.NET 7.x	C:\Program Files\dotnet\shared\Microsoft.NETCore.App\7.0.x\dbgshim.dll
.NET 8.x	C:\Program Files\dotnet\shared\Microsoft.NETCore.App\8.0.x\dbgshim.dll
.NET 9.x	C:\Program Files\dotnet\shared\Microsoft.NETCore.App\9.0.x\dbgshim.dll

# Example: Setup for .NET 8 debugging
copy "C:\Program Files\dotnet\shared\Microsoft.NETCore.App\8.0.x\dbgshim.dll" "D:\Bin\netcoredbg\"

[!TIP] This MCP server automatically detects mismatches and warns you during start_debug.

[!IMPORTANT] Prefer start_debug over attach_debug

attach_debug has significant upstream limitations in netcoredbg — stack traces and variable inspection may be incomplete or empty.

---

Installation

Requirements

• Python 3.10+
• netcoredbg
• .NET SDK (for the apps you're debugging)
• Pillow (installed automatically — required for screenshot annotation)

Install the MCP Server

# Install from PyPI (recommended)
uv pip install netcoredbg-mcp

# Or with pip
pip install netcoredbg-mcp

Install from Source (Development)

git clone https://github.com/thebtf/netcoredbg-mcp.git
cd netcoredbg-mcp
uv sync

Install netcoredbg

Download from Samsung/netcoredbg releases and extract to D:\Bin\netcoredbg\

---

Upgrading

pip install --upgrade netcoredbg-mcp

From v0.1.x to v0.2.0

Breaking changes:

• Tool response format changed: {"success": true, "data": ...} → {"state": "...", "next_actions": [...], "data": ...}. Update any hardcoded response parsing.
• resources.py removed (resources now inline in server.py).

New dependencies:

• Pillow>=10.0 (for screenshot annotation) — installed automatically via pip.

New features to explore:

• ui_take_screenshot(), ui_take_annotated_screenshot() — visual UI access
• cleanup_processes() — replaces manual taskkill
• restart_debug() — rebuild + relaunch in one call
• investigate("NullReferenceException") — parameterized debugging prompts

---

Configuration

Environment Variable

Set NETCOREDBG_PATH in your PowerShell profile (%USERPROFILE%\Documents\PowerShell\Microsoft.PowerShell_profile.ps1):

$env:NETCOREDBG_PATH = "D:\Bin\netcoredbg\netcoredbg.exe"

Base Server Configuration

All clients use this same server definition:

{
  "netcoredbg": {
    "command": "netcoredbg-mcp",
    "args": ["--project-from-cwd"],
    "env": {
      "NETCOREDBG_PATH": "D:\\Bin\\netcoredbg\\netcoredbg.exe"
    }
  }
}

Running from Source (Development)

If running from cloned repository instead of PyPI:

{
  "netcoredbg": {
    "command": "uv",
    "args": ["run", "--project", "D:\\Dev\\netcoredbg-mcp", "netcoredbg-mcp", "--project-from-cwd"],
    "env": {
      "NETCOREDBG_PATH": "D:\\Bin\\netcoredbg\\netcoredbg.exe"
    }
  }
}

[!IMPORTANT] Use uv run --project NOT uv --directory. The --directory flag changes CWD, breaking --project-from-cwd.

---

Client Setup

CLI Agents

Claude Code

claude mcp add --scope user netcoredbg -- netcoredbg-mcp --project-from-cwd

Verify: claude mcp list

Codex CLI (OpenAI)

Config: %USERPROFILE%\.codex\config.toml

[mcp_servers.netcoredbg]
command = "netcoredbg-mcp"
args = ["--project-from-cwd"]

[mcp_servers.netcoredbg.env]
NETCOREDBG_PATH = "D:\\Bin\\netcoredbg\\netcoredbg.exe"

Or via CLI: codex mcp add netcoredbg -- netcoredbg-mcp --project-from-cwd

Gemini CLI (Google)

Config: %USERPROFILE%\.gemini\settings.json

{
  "mcpServers": {
    "netcoredbg": {
      "command": "netcoredbg-mcp",
      "args": ["--project-from-cwd"],
      "env": {
        "NETCOREDBG_PATH": "D:\\Bin\\netcoredbg\\netcoredbg.exe"
      }
    }
  }
}

Cline

Config: Open Cline → MCP Servers icon → Configure → "Configure MCP Servers"

{
  "mcpServers": {
    "netcoredbg": {
      "command": "netcoredbg-mcp",
      "args": ["--project-from-cwd"],
      "env": {
        "NETCOREDBG_PATH": "D:\\Bin\\netcoredbg\\netcoredbg.exe"
      }
    }
  }
}

Roo Code

Config: %USERPROFILE%\.roo\mcp.json or .roo\mcp.json in project

{
  "mcpServers": {
    "netcoredbg": {
      "command": "netcoredbg-mcp",
      "args": ["--project-from-cwd"],
      "env": {
        "NETCOREDBG_PATH": "D:\\Bin\\netcoredbg\\netcoredbg.exe"
      }
    }
  }
}

Desktop Apps

Claude Desktop

Config: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "netcoredbg": {
      "command": "netcoredbg-mcp",
      "args": ["--project-from-cwd"],
      "env": {
        "NETCOREDBG_PATH": "D:\\Bin\\netcoredbg\\netcoredbg.exe"
      }
    }
  }
}

IDE Extensions

Cursor

Config: %USERPROFILE%\.cursor\mcp.json

{
  "mcpServers": {
    "netcoredbg": {
      "command": "netcoredbg-mcp",
      "args": ["--project-from-cwd"],
      "env": {
        "NETCOREDBG_PATH": "D:\\Bin\\netcoredbg\\netcoredbg.exe"
      }
    }
  }
}

Windsurf

Config: %USERPROFILE%\.codeium\windsurf\mcp_config.json

{
  "mcpServers": {
    "netcoredbg": {
      "command": "netcoredbg-mcp",
      "args": ["--project-from-cwd"],
      "env": {
        "NETCOREDBG_PATH": "D:\\Bin\\netcoredbg\\netcoredbg.exe"
      }
    }
  }
}

VS Code + Continue

Config: %USERPROFILE%\.continue\config.json

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "uv",
          "args": ["run", "--project", "D:\\Dev\\netcoredbg-mcp", "netcoredbg-mcp", "--project-from-cwd"],
          "env": {
            "NETCOREDBG_PATH": "D:\\Bin\\netcoredbg\\netcoredbg.exe"
          }
        }
      }
    ]
  }
}

Project-Scoped Config

.mcp.json (in project root)

Add to your .NET project root for automatic loading:

{
  "mcpServers": {
    "netcoredbg": {
      "command": "uv",
      "args": ["run", "--project", "D:\\Dev\\netcoredbg-mcp", "netcoredbg-mcp"],
      "env": {
        "NETCOREDBG_PATH": "D:\\Bin\\netcoredbg\\netcoredbg.exe",
        "NETCOREDBG_PROJECT_ROOT": "${workspaceFolder}"
      }
    }
  }
}

[!NOTE] With project-scoped config, use NETCOREDBG_PROJECT_ROOT instead of --project-from-cwd.

---

First Debug Session

The Long-Poll Pattern

Execution tools (continue_execution, step_over, step_into, step_out) block until the program stops. No polling. One call = one answer.

Agent: continue_execution()
       ↓ blocks...
       ↓ program runs...
       ↓ breakpoint hit!
       ← returns: { state: "stopped", reason: "breakpoint", location: {...}, source_context: "..." }

Typical Workflow

1. start_debug       → Launch with pre_build (builds + starts debugger)
2. add_breakpoint    → Set breakpoints in source files
3. continue          → Blocks until breakpoint hit (returns location + source context)
4. get_call_stack    → Full stack trace (source context included in top frame)
5. get_variables     → Examine locals, arguments, captures
6. step_over         → Blocks until next line (returns new location + source)
7. get_output_tail   → Check program output (user cannot see it)
8. stop_debug        → End session

Example: start_debug with Pre-build

start_debug(
    program="/path/to/MyApp.exe",      # Auto-resolves to .dll for .NET 6+
    pre_build=True,                     # Build before launching (default)
    build_project="/path/to/MyApp.csproj",
    build_configuration="Debug",
    stop_at_entry=False
)
# Response: { state: "running", app_type: "gui", message: "GUI application detected..." }

Smart .exe to .dll Resolution

For .NET 6+ applications (WPF, WinForms, Console), the SDK creates:

• App.exe — Native host launcher
• App.dll — Actual managed code

Debugging .exe causes a "deps.json conflict" error. This MCP server automatically resolves .exe to .dll when a matching .dll and .runtimeconfig.json exist.

---

GUI App Debugging

GUI apps (WPF, WinForms, Avalonia) freeze when the debugger pauses — the UI thread stops, windows stop painting, buttons stop responding.

The Golden Rule

Never set breakpoints before the window is visible.

Correct Workflow

1. start_debug(program="App.dll", build_project="App.csproj")
   → Response includes app_type="gui"

2. ui_get_window_tree()
   → Confirm the window loaded

3. ui_take_annotated_screenshot()
   → See the UI with numbered interactive elements

4. add_breakpoint(file="MainViewModel.cs", line=42)
   → NOW set breakpoints (window is visible)

5. ui_click(automation_id="btnSave")
   → Trigger the code path via UI interaction

6. continue_execution()
   → Blocks until breakpoint hit — inspect state

7. get_call_stack() → get_variables(ref=...)
   → Read locals at breakpoint

8. continue_execution()
   → RESUME — the app is frozen while you inspect

9. stop_debug()

Exception: Startup Debugging

If the bug IS in startup code, use stop_at_entry:

start_debug(program="App.dll", ..., stop_at_entry=True)
# App pauses at Main() — before any UI
step_over()  # step through init one line at a time

---

Visual Inspection

Screenshots

ui_take_screenshot()

Returns base64 PNG of the app window — see exactly what the user sees. Use for verifying layout, checking rendering issues, finding elements not in the automation tree.

Set-of-Mark Annotation

ui_take_annotated_screenshot(max_depth=3, interactive_only=True)

Returns a screenshot with numbered red boxes around interactive elements plus a JSON element index:

{
  "image": "base64_png...",
  "elements": [
    {"id": 1, "name": "Save", "type": "Button", "automationId": "btnSave"},
    {"id": 2, "name": "", "type": "TextBox", "automationId": "txtName"}
  ]
}

Then click by number:

ui_click_annotated(element_id=1)   # clicks "Save" button

Use when elements lack an AutomationId, when you need spatial context, or when multiple similar elements exist.

Multi-Row Selection

For selecting multiple rows in a DataGrid, use UIA patterns instead of coordinate clicking:

ui_select_items(automation_id="dataGrid", indices=[4,5,6,7,8], mode="replace")

Works for off-screen rows without scrolling.

---

Available Tools

Debug Control (11 tools)

Tool	Description
start_debug	Launch program under debugger with optional pre-build. Auto-detects GUI apps.
attach_debug	Attach to running process. Limited functionality (upstream limitation).
stop_debug	Stop the debug session and release resources.
restart_debug	Restart session with same config. Optional rebuild.
continue_execution	Resume execution. Blocks until stopped event.
pause_execution	Pause a running program. Returns immediately.
step_over	Step to next line. Blocks until step completes. Returns source context.
step_into	Step into function call. Blocks until step completes.
step_out	Step out of current function. Blocks until step completes.
get_step_in_targets	List callable functions on the current line — pick which one to step into.
get_debug_state	Get current session state, threads, position. Read-only.

start_debug Parameters

Parameter	Type	Description
program	string	Path to .exe or .dll (auto-resolved)
cwd	string?	Working directory
args	list?	Command line arguments
env	dict?	Environment variables
stop_at_entry	bool	Stop at program entry point
pre_build	bool	Build before launching (default: true)
build_project	string?	Path to .csproj (required if pre_build)
build_configuration	string	"Debug" or "Release"

Breakpoints (6 tools)

Tool	Description
add_breakpoint	Set breakpoint at file:line with optional condition and hit count.
remove_breakpoint	Remove a breakpoint by file and line.
list_breakpoints	List all active breakpoints (optionally filtered by file).
clear_breakpoints	Clear all breakpoints or all in a specific file. Destructive.
add_function_breakpoint	Break on function entry by name. Useful when line number unknown.
configure_exceptions	Set exception breakpoints: ["all"], ["user-unhandled"], or [].

Inspection (11 tools)

Tool	Description
get_threads	List all threads with IDs and names.
get_call_stack	Stack trace for a thread. Includes source context for top frame.
get_scopes	Get variable scopes for a stack frame (returns references).
get_variables	Read variable values from a scope reference. Supports filter, start, count paging.
evaluate_expression	Evaluate a C# expression in the current debug context.
quick_evaluate	Fast expression evaluation — single value, no side-effect warnings.
set_variable	Modify a variable's value during debugging (test hypotheses live).
get_exception_info	Get exception type, message, and inner exception when stopped on throw.
get_exception_context	Full exception context including inner exceptions and stack frames.
analyze_collection	Count, null check, find duplicates, and compute stats on a collection variable.
summarize_object	Recursive summary of an object's fields and nested objects with cycle detection.

Output (4 tools)

Tool	Description
get_output	Full stdout/stderr from the debugged process. Optional clear.
get_output_tail	Last N lines of output. Lightweight recent-output check.
search_output	Regex search through output with context lines.
get_build_diagnostics	Full build warnings (hidden by default in start_debug).

Tracepoints (4 tools)

Tool	Description
add_tracepoint	Add a client-side tracepoint: pause, evaluate expression, log, resume — without netcoredbg support.
remove_tracepoint	Remove a tracepoint by file and line.
get_trace_log	Retrieve the tracepoint evaluation log.
clear_trace_log	Clear the tracepoint log.

Snapshots (3 tools)

Tool	Description
create_snapshot	Capture all local variables at the current stop into a named snapshot (FIFO, max 20).
diff_snapshots	Compare two snapshots and show added, removed, and changed variables.
list_snapshots	List all stored snapshots with metadata.

UI Automation (17 tools)

Tool	Description
ui_get_window_tree	Visual tree of the app window (AutomationId, type, name, enabled). Supports root_id and xpath.
ui_find_element	Find element by AutomationId, name, or control type. Supports root_id and xpath.
ui_set_focus	Set keyboard focus to an element.
ui_send_keys	Send keyboard input to a specific element (pywinauto syntax).
ui_send_keys_focused	Send keys to currently focused element (no re-search).
ui_click	Click an element by AutomationId, name, or type. Supports root_id and xpath.
ui_right_click	Right-click to open context menus.
ui_double_click	Double-click an element.
ui_invoke	Invoke the default action of an element (e.g. press a button via UIA InvokePattern).
ui_toggle	Toggle a checkbox, radio button, or toggle switch via UIA TogglePattern.
ui_file_dialog	Interact with standard open/save file dialogs — type path and confirm.
ui_select_items	Multi-select items by index in DataGrid/ListView (UIA pattern).
ui_scroll	Scroll a control (up/down/left/right).
ui_drag	Drag from one element to another.
ui_take_screenshot	Screenshot of the app window as base64 PNG.
ui_take_annotated_screenshot	Screenshot with numbered element overlays (Set-of-Mark).
ui_click_annotated	Click an element by its annotation ID from the last annotated screenshot.

Process Management (1 tool)

Tool	Description
cleanup_processes	View or terminate tracked debug processes. Safe alternative to taskkill.

---

MCP Resources

Resource URI	Description
debug://state	Current session state (JSON): status, stop reason, threads, process info
debug://breakpoints	All active breakpoints (JSON): file paths, lines, conditions, verified status
debug://output	Debug console output (plain text): stdout/stderr from debugged process
debug://threads	Current threads (JSON): thread IDs and names for the debugged process

Resources emit notifications/resources/updated when their content changes, enabling real-time subscriptions.

---

MCP Prompts

Prompts are built-in debugging guides the agent can invoke for structured workflows.

Prompt	Description
debug	Complete debugging guide: state machine, tool usage, anti-patterns, valid actions by state
debug-gui	WPF/Avalonia/WinForms workflow: breakpoint timing, UI interaction while debugging
debug-exception	Step-by-step exception investigation protocol with common .NET exception table
debug-visual	Screenshot and Set-of-Mark annotation workflow for visual UI inspection
debug-mistakes	9 concrete anti-patterns with WRONG/CORRECT examples
investigate(symptom)	Targeted investigation plan for a specific exception type or symptom. Includes playbooks for NullReference, InvalidOperation, TaskCanceled, ObjectDisposed, deadlocks, crashes, and performance issues.
debug-scenario(problem)	Step-by-step debugging plan for a specific problem description. Generates exact tool calls to execute.

---

Multi-Agent Safety (mcp-mux)

When served through mcp-mux (transparent MCP multiplexer), netcoredbg-mcp operates in session-aware mode:

• Server declares x-mux: {sharing: "session-aware"} capability
• Each request carries _meta.muxSessionId identifying the calling agent
• First agent to call a mutating tool (start_debug, step, etc.) claims ownership
• Other agents get: "Debug session is owned by another agent (session sess_XXX)"
• Read-only tools (get_variables, screenshots) work for all agents
• Ownership auto-releases after 60 seconds of inactivity

This enables safe parallel work — one agent debugs while others observe.

---

Architecture

graph TB
    subgraph MCP["MCP Server (Python)"]
        S[server.py<br/>286 lines]
        subgraph Tools["Tool Modules"]
            TD[tools/debug.py]
            TB[tools/breakpoints.py]
            TI[tools/inspection.py]
            TO[tools/output.py]
            TU[tools/ui.py]
            TP[tools/process.py]
        end
        PR[prompts.py]
        SM[session/manager.py]
        SS[session/state.py]
        MX[mux.py]
        REG[process_registry.py]
        BM[build/manager.py]
        BP[build/policy.py]
        AT[utils/app_type.py]
        SC[utils/source.py]
        VC[utils/version.py]
        UIA[ui/automation.py]
        USS[ui/screenshot.py]
    end

    subgraph DAP["DAP Client"]
        DC[dap/client.py]
        DP[dap/protocol.py]
        DE[dap/events.py]
    end

    S --> Tools
    S --> PR
    S --> SM
    S --> MX
    Tools --> SM
    SM --> DC
    SM --> BM
    SM --> REG
    TU --> UIA
    TU --> USS
    DC --> DP
    DC --> DE

    DC <-->|stdio JSON-RPC| NDB[netcoredbg<br/>DAP Server]
    NDB <-->|CoreCLR Debug API| APP[.NET App]

    style MCP fill:#1a1a2e,stroke:#6f42c1,color:#fff
    style Tools fill:#16213e,stroke:#0f3460,color:#fff
    style DAP fill:#16213e,stroke:#0f3460,color:#fff

How It Works

1. MCP Layer — server.py registers 66 tools, 4 resources, and 7 prompts via FastMCP
2. Tool Modules — 6 focused modules (debug, breakpoints, inspection, output, UI, process) keep the server thin
3. Session Manager — Manages debug session lifecycle, state machine, path validation, event handling
4. DAP Client — Communicates with netcoredbg via Debug Adapter Protocol (JSON-RPC over stdio)
5. Build Manager — Builds projects before debugging, filters warnings, stores diagnostics
6. Process Registry — PID file tracking for all spawned processes; cleanup on startup and via tool
7. UI Automation — pywinauto-based Windows UI Automation for WPF/WinForms/Avalonia interaction
8. Screenshot Engine — Window capture + Pillow-based Set-of-Mark annotation
9. Mux Integration — Session ownership guards for safe multi-agent operation via mcp-mux
10. Version Checker — Validates dbgshim.dll compatibility with target runtime

---

Command Line Options

Option	Description
--project PATH	Explicit project root path
--project-from-cwd	Auto-detect project from CWD

Environment Variables

Variable	Description
NETCOREDBG_PATH	Required. Path to netcoredbg executable
NETCOREDBG_PROJECT_ROOT	Project root path (alternative to --project)
NETCOREDBG_ALLOWED_PATHS	Additional allowed path prefixes (comma-separated) for worktree support
NETCOREDBG_SCREENSHOT_MAX_WIDTH	Max screenshot width in pixels (default: 1568)
NETCOREDBG_SCREENSHOT_QUALITY	Screenshot WebP/JPEG quality 1-100 (default: 80)
NETCOREDBG_MAX_TRACE_ENTRIES	Max tracepoint log entries (default: 1000)
NETCOREDBG_EVALUATE_TIMEOUT	Expression evaluation timeout in seconds (default: 0.5)
NETCOREDBG_RATE_LIMIT_INTERVAL	Tracepoint rate limit interval (default: 0.1 = max 10/sec)
NETCOREDBG_MAX_SNAPSHOTS	Max state snapshots per session (default: 20)
NETCOREDBG_MAX_VARS_PER_SNAPSHOT	Max variables per snapshot (default: 200)
NETCOREDBG_MAX_OUTPUT_BYTES	Max output buffer size in bytes (default: 10MB)
NETCOREDBG_MAX_OUTPUT_ENTRY	Max single output entry size (default: 100KB)
NETCOREDBG_SESSION_TIMEOUT	Session ownership timeout in seconds (default: 60)
NETCOREDBG_STACKTRACE_DELAY_MS	Diagnostic delay (ms) before stackTrace requests — helps diagnose timing issues
FLAUI_BRIDGE_PATH	Path to FlaUIBridge.exe (auto-detected if not set)
LOG_LEVEL	Logging level: DEBUG, INFO, WARNING, ERROR
LOG_FILE	Path to log file for diagnostics

---

Troubleshooting

Empty call stack / E_NOINTERFACE (0x80004002)

Symptom: get_call_stack returns empty array or error containing 0x80004002.

Cause: dbgshim.dll version mismatch between netcoredbg and target runtime.

Solution:

1. Check the warning from start_debug — it shows exact versions
2. Copy the correct dbgshim.dll:

# Find your .NET runtime versions
dir "C:\Program Files\dotnet\shared\Microsoft.NETCore.App\"

# Copy matching version (e.g., for .NET 8 app)
copy "C:\Program Files\dotnet\shared\Microsoft.NETCore.App\8.0.x\dbgshim.dll" "D:\Bin\netcoredbg\"

deps.json conflict error

Symptom: Launch fails with "assembly has already been found but with a different file extension".

Cause: Debugging .exe instead of .dll for a .NET 6+ app.

Solution: Should be auto-resolved. If not, explicitly pass the .dll path:

program: "App.dll"  # instead of "App.exe"

Program not found with pre_build

Symptom: start_debug with pre_build: true fails saying program doesn't exist.

Cause: Old version that validated path before building.

Solution: Update to latest version. Path validation is now deferred until after build.

Breakpoints not hitting

Symptom: Breakpoints are set but never triggered.

Possible causes:

1. Wrong configuration (Release instead of Debug)
2. Source mismatch (binary doesn't match source)
3. JIT optimization affecting line mappings

Solution: Use pre_build: true to ensure fresh Debug build.

Attach mode: empty stack traces

Symptom: After attaching to running process, get_call_stack returns empty.

Cause: netcoredbg doesn't support justMyCode in attach mode (upstream limitation).

Solution: Use start_debug instead. If you must attach, expect limited functionality.

GUI app window never appears

Symptom: After start_debug, the app window doesn't show up.

Cause: A breakpoint was set before launch and hit during window initialization, freezing the UI thread.

Solution: Remove all breakpoints before start_debug. Set them after ui_get_window_tree() confirms the window is visible.

Orphaned debugger processes

Symptom: Multiple netcoredbg or dotnet processes accumulating after debug sessions.

Cause: Debug sessions terminated without proper cleanup.

Solution:

cleanup_processes(force=True)   # kills only processes tracked by this server

The server also cleans up stale PID files on startup.

Build warnings causing runtime failures

Symptom: Build succeeds but app crashes or behaves unexpectedly.

Cause: Build warnings (hidden by default) often predict runtime issues:

• CS8602 nullable dereference → NullReferenceException
• NU1701 compatibility → assembly load failures
• CS4014 unawaited async → swallowed exceptions

Solution:

get_build_diagnostics()   # reveals all warnings hidden during start_debug

---

Limitations

• Single session — One debug session at a time (by design for state machine clarity)
• Attach mode — Limited functionality due to netcoredbg upstream limitation
• dbgshim version — Must manually match version to target runtime
• Windows focus — Primary development/testing on Windows (Linux/macOS: UI automation unavailable, core debugging may work)
• mcp-mux multi-agent — Session ownership prevents conflicting mutations; only the session that started debugging can modify state. Other sessions get read-only access.

---

License

MIT