# Troubleshooting Guide

This guide provides solutions for common issues you might encounter when setting up and using the Debug MCP Server.

## Connection Issues

### MCP Server Shows "Disconnected" in VS Code

**Problem**: The debug-mcp-server shows as disconnected in the Claude VS Code extension.

**Solutions**:

1. Verify the command path in your MCP settings:
   ```json
   "command": "node",
   "args": ["C:\\path\\to\\mcp-debugger\\dist\\index.js", "stdio"]
   ```
   Ensure the path points to the correct location of the built server. The entry point is `dist/index.js` when building from source. (The NPX package `@debugmcp/mcp-debugger` exposes `dist/cli` as the executable shim, which loads `dist/cli.mjs`.)

2. Check for spaces in file paths:
   - Windows paths with spaces require proper quoting

3. Run the server manually to see errors:
   - Open a terminal
   - Navigate to the project directory
   - Run: `node dist/index.js stdio`
   - Check for any error messages

4. Restart VS Code:
   - Sometimes a simple restart of VS Code can resolve connection issues

### ENOENT Error When Starting Server

**Problem**: You see an error like: `spawn node c:/path/to/debug-mcp-server/dist/index.js ENOENT`

**Solutions**:

1. Check if the path exists:
   - Verify that the `dist` directory and `index.js` entry point exist
   - Run `npm run build` if the dist folder is missing

2. Fix path formatting:
   - Windows paths might need backslashes instead of forward slashes
   - Ensure your MCP settings point to `dist/index.js` (monorepo root) or use the NPX command `npx @debugmcp/mcp-debugger stdio`

3. Use quotes for paths with spaces:
   - If your path contains spaces, ensure it's properly quoted in the command

## Python Issues

### Python Not Found

**Problem**: The server can't find a Python installation.

**Solutions**:

1. Check if Python is installed and in PATH:
   ```
   python --version
   ```

2. Set the PYTHON_PATH or PYTHON_EXECUTABLE environment variable:
   - Windows: `set PYTHON_PATH=C:\path\to\python.exe`
   - Unix: `export PYTHON_PATH=/path/to/python`
   - Alternative: `PYTHON_EXECUTABLE` is also checked as a fallback if `PYTHON_PATH` is not set

3. Specify Python path directly in the debug session:
   - When creating a debug session through Claude, specify the executablePath

### debugpy Not Found or Installation Fails

**Problem**: The server can't find debugpy or fails to install it.

**Solutions**:

1. Install debugpy manually:
   ```
   pip install debugpy
   ```

2. Check pip installation:
   ```
   pip --version
   ```

3. Try installing with Python module syntax:
   ```
   python -m pip install debugpy
   ```

4. Check for permissions issues:
   - On Unix systems, you might need sudo
   - On Windows, try running as Administrator

## Path Resolution

### Understanding How Paths Are Resolved

**Problem**: File paths in debugging tools are resolved differently depending on your MCP client.

**Key Concept**: File paths are resolved relative to your MCP client's working directory, not the debugger's location.

**Solutions by Client**:

1. **VS Code with Cline**:
   - Paths resolve from VS Code's working directory
   - Check your workspace folder in VS Code
   - Example: If VS Code is open in `C:\projects\myapp`, then `test.py` resolves to `C:\projects\myapp\test.py`

2. **Claude Desktop**:
   - Paths resolve from the desktop client's directory
   - This may vary by OS and installation method

3. **Other MCP Clients**:
   - Check your client's documentation for working directory behavior

**Best Practices**:

1. **Use Absolute Paths**: To avoid confusion, always use absolute paths:
   ```json
   {
     "file": "C:/Users/user/projects/myapp/test.py",
     "line": 10
   }
   ```

2. **Check Error Messages**: The debugger now provides helpful context in errors:
   ```
   File not found: 'test.py'
   Resolved path: 'C:\Users\user\AppData\Local\Programs\Microsoft VS Code\test.py'
   Container mode: false
   Suggestion: Check that the file exists and the path is correct
   Note: Relative paths are resolved from: C:\Users\user\AppData\Local\Programs\Microsoft VS Code
   ```

3. **Container Mode**: When running in Docker, paths are prefixed with the workspace root:
   - The `MCP_WORKSPACE_ROOT` environment variable must be set in container mode (there is no code default; the Docker image may set it, e.g., to `/workspace`)
   - Host: `test.py` → Container: `/workspace/test.py`
   - The debugger handles this translation automatically

4. **Host Mode**: Relative paths are rejected by `SimpleFileChecker` for file-based operations (e.g., `set_breakpoint`, `start_debugging`) -- always use absolute paths when running outside Docker

## Debugging Session Issues

### Breakpoints Not Hit

**Problem**: Debugging starts, but breakpoints are never hit.

**Solutions**:

1. Verify breakpoint is set in the correct file:
   - Use absolute paths when setting breakpoints
   - Check file paths in Claude's responses

2. Check breakpoint verification:
   - Claude should report if a breakpoint was "verified"
   - Unverified breakpoints won't work

3. Make sure script execution reaches the breakpoint:
   - Set breakpoints in code paths that are definitely executed
   - Add a breakpoint at the script entry point to confirm debugging works

### Session Creation Fails

**Problem**: Unable to create a debug session.

**Solutions**:

1. Check server logs for errors:
   - Logs should show why session creation failed

2. Verify Python detection is working:
   - Server logs will show if Python was detected
   - Make sure Python is in PATH or specified via PYTHON_PATH

3. Ensure debugpy communication works:
   - Session ports are dynamically allocated by the OS (port 0 is requested, so each session gets a unique port); port 5679 is only used by Docker test fixtures and is not the default session port
   - Check server logs if a session fails to start — the assigned port will be logged

## Communication Issues

### Claude Can't Connect to Debugging Session

**Problem**: Claude successfully starts the debug server but can't communicate with it properly.

**Solutions**:

1. Restart the conversation:
   - Sometimes a fresh conversation helps

2. Verify all tools are registered properly:
   - Check the server logs to see if all tools are registered
   - Make sure the server is up and running

3. Try a simple command first:
   - Start with listing debug sessions
   - Then create a debug session
   - Gradually build up to more complex operations

If you encounter an issue not covered in this guide, check:
1. The server logs for specific error messages
2. The VS Code output panel for Claude extension logs
3. Any error responses directly from Claude when using debugging commands
