Debugging VS Code

Overview

VS Code provides comprehensive debugging capabilities for its own development. You can debug the main process, extension host, renderer process, and more using the pre-configured launch configurations.

All launch configurations are defined in .vscode/launch.json at the root of the repository.

Quick Start

Open VS Code

Open the VS Code repository in VS Code:

code /path/to/vscode

Start Watch Mode

Ensure code is being compiled:

npm run watch

Launch Debugger

Press F5 or select the “VS Code” configuration from the Run and Debug view.

Wait for Launch

A new VS Code window will open with the debugger attached to all processes.

If launching times out, run ./scripts/code.sh first to set up Electron, or increase the timeout values in launch.json.

Debug Configurations

Main Configurations

VS Code (Full)
VS Code (Hot Reload)
Launch VS Code Internal
Main Process

Configuration: VS CodeType: Compound (multiple processes)Launches VS Code with debuggers attached to:

Main Process
Renderer Process
Extension Host
Shared Process

Usage: Press F5 or select from debug dropdownEnvironment Variables:

VSCODE_EXTHOST_WILL_SEND_SOCKET=null
VSCODE_SKIP_PRELAUNCH=1
VSCODE_DEV_DEBUG_OBSERVABLES=1

User Data: ~/.vscode-oss-dev

Configuration: VS Code (Hot Reload)Type: Compound with Vite integrationEnables hot reloading for faster development iteration:

Real-time code updates without restart
Vite-powered Monaco Editor
All debuggers attached

Pre-launch Task: Launch Monaco Editor ViteSpecial Environment:

VSCODE_DEV_SERVER_URL=http://localhost:5199/build/vite/workbench-vite-electron.html
DEV_WINDOW_SRC=http://localhost:5199/build/vite/workbench-vite-electron.html

Configuration: Launch VS Code InternalType: Chrome debuggerLaunches VS Code with Chrome DevTools attached to the renderer process.Runtime Arguments:

--inspect-brk=5875
--no-cached-data
--crash-reporter-directory=${workspaceFolder}/.profile-oss/crashes
--disable-features=CalculateNativeWinOcclusion
--disable-extension=vscode.vscode-api-tests

Debug Port: 9222

Configuration: Main ProcessType: Node debuggerDebugs only the Electron main process:

Application lifecycle
Window management
Native integration

Launch Script:

Linux/macOS: scripts/code.sh
Windows: scripts/code.bat

Debug Port: 5875

Process-Specific Debugging

Extension Host

Port: 5870Attach to the extension host process where extensions run.Launch Config: Attach to Extension HostUse Case: Debug extension execution, API calls, language features

Shared Process

Port: 5879Attach to the shared process that handles background tasks.Launch Config: Attach to Shared ProcessUse Case: Debug services shared across windows

Search Process

Port: 5876Attach to the search process for debugging file searching.Launch Config: Attach to Search ProcessUse Case: Debug search functionality, ripgrep integration

Pty Host Process

Port: 5877Attach to the pseudoterminal host process.Launch Config: Attach to Pty Host ProcessUse Case: Debug terminal functionality, shell integration

Debugging Specific Components

Built-in Extensions

Extension Tests
Language Features
Custom Extension

Run and debug extension tests:

{
  "type": "extensionHost",
  "name": "VS Code API Tests (single folder)",
  "args": [
    "${workspaceFolder}/extensions/vscode-api-tests/testWorkspace",
    "--extensionDevelopmentPath=${workspaceFolder}/extensions/vscode-api-tests",
    "--extensionTestsPath=${workspaceFolder}/extensions/vscode-api-tests/out/singlefolder-tests",
    "--disable-extensions"
  ]
}

Available extension test configurations:

API Tests (single folder)
API Tests (workspace)
Git Tests
Markdown Tests
TypeScript Tests
Emmet Tests

Debug language feature extensions:TypeScript Extension:

# Select: "TypeScript Extension Tests"
# Workspace: extensions/typescript-language-features/test-workspace

Markdown Extension:

# Select: "Markdown Extension Tests"
# Workspace: extensions/markdown-language-features/test-workspace

Debug any built-in extension:

{
  "type": "extensionHost",
  "name": "Launch Built-in Extension",
  "runtimeExecutable": "${execPath}",
  "args": [
    "--extensionDevelopmentPath=${workspaceRoot}/extensions/[extension-name]"
  ]
}

Unit Tests

All Unit Tests
Current File Tests
Manual Test Run

Configuration: Debug Unit TestsType: CompoundRuns all unit tests with debugger attached:

# Test entry point
test/unit/electron/index.js

Runtime: Electron binary from .build/electron/Environment:

MOCHA_COLORS=true

Configuration: Debug Unit Tests (Current File)Debug tests in the currently open file:

{
  "args": [
    "--remote-debugging-port=9222",
    "--run",
    "${relativeFile}"
  ]
}

Usage: Open a test file and press F5

Run unit tests from command line with inspect:

# Run with debugger paused at start
./scripts/test.sh --inspect-brk

# Run specific test file
./scripts/test.sh --run src/vs/editor/test/common/model/model.test.ts

# Filter by test name
./scripts/test.sh --grep "should validate range"

Web Development

VS Code Web (Chrome)
VS Code Server
Manual Launch

Configuration: VS Code Web (Chrome)Launch VS Code in Chrome for web development:

{
  "type": "chrome",
  "url": "http://localhost:8080",
  "preLaunchTask": "Run code web"
}

The pre-launch task starts the web server automatically.

Configuration: VS Code Server (Web, Chrome)Launch VS Code in server mode:

{
  "url": "http://localhost:8080?tkn=dev-token",
  "preLaunchTask": "Run code server"
}

Start web server manually:

# Web mode
./scripts/code-web.sh

# Server mode
./scripts/code-server.sh

Then attach Chrome debugger to http://localhost:8080

Advanced Debugging Techniques

Debugging with Source Maps

VS Code is compiled TypeScript with source maps:

Source Map Configuration

Source maps are configured in launch.json:

{
  "outFiles": [
    "${workspaceFolder}/out/**/*.js"
  ],
  "resolveSourceMapLocations": [
    "${workspaceFolder}/out/**/*.js"
  ],
  "perScriptSourcemaps": "yes"
}

Set Breakpoints

Set breakpoints directly in TypeScript source files in src/. The debugger will map them to the compiled JavaScript.

View Original Source

When paused at a breakpoint, the debugger shows the original TypeScript source.

Debugging Observables

To debug observables, install the extension ms-vscode.debug-value-editor.

Enable observable debugging:

{
  "env": {
    "VSCODE_DEV_DEBUG_OBSERVABLES": "1"
  }
}

This allows you to inspect observable values in the debugger.

Debugging Native Modules

For debugging native Node modules:

# Launch with lldb
lldb .build/electron/Code\ -\ OSS.app/Contents/MacOS/Code\ -\ OSS

# Set breakpoints in native code
(lldb) breakpoint set --name nativeFunction

# Launch with gdb
gdb .build/electron/code-oss

# Set breakpoints
(gdb) break nativeFunction

Remote Debugging

Debug VS Code running on a remote machine:

Start VS Code with Debug Port

On the remote machine:

./scripts/code.sh --inspect=0.0.0.0:9229

Forward Port

Forward the debug port via SSH:

ssh -L 9229:localhost:9229 user@remote-host

Attach Debugger

Create a launch configuration:

{
  "type": "node",
  "request": "attach",
  "name": "Attach to Remote",
  "address": "localhost",
  "port": 9229
}

Debugging Tips

Use Compound Configurations

The “VS Code” compound configuration attaches to all processes at once, giving you complete debugging coverage:

{
  "name": "VS Code",
  "configurations": [
    "Launch VS Code Internal",
    "Attach to Main Process",
    "Attach to Extension Host",
    "Attach to Shared Process"
  ]
}

Developer Tools

Access Chrome DevTools in the running instance:

Command Palette: Developer: Toggle Developer Tools
Keyboard: Cmd/Ctrl + Shift + I

DevTools are useful for:

Inspecting DOM elements
Viewing console logs
Network requests
Performance profiling

Logging

Enable detailed logging:

# Electron logging
export ELECTRON_ENABLE_LOGGING=1

# VS Code logging
./scripts/code.sh --log trace

# Specific log level
./scripts/code.sh --log-level=trace

Logs are saved to:

macOS: ~/Library/Application Support/Code - OSS/logs
Linux: ~/.config/Code - OSS/logs
Windows: %APPDATA%\Code - OSS\logs

Disable Extensions

Disable extensions to isolate issues:

./scripts/code.sh --disable-extensions

Or selectively disable:

./scripts/code.sh --disable-extension=vscode.vscode-api-tests

Clean User Data

Start with fresh user data:

# Temporary directory
./scripts/code.sh --user-data-dir=/tmp/vscode-test

# The dev profile
rm -rf ~/.vscode-oss-dev

Debug Console

Use the Debug Console for REPL during debugging:

Evaluate expressions
Call functions
Inspect variables

Example:

> this._editor.getModel().getValue()
> this._onDidChange.fire()

Debugging Smoke Tests

Run smoke tests with debugging:

# Run smoke tests
npm run smoketest

# Without recompilation
npm run smoketest-no-compile

# With specific test
cd test/smoke && node test/index.js --grep "should open file"

Launch configuration:

{
  "name": "Launch Smoke Test",
  "program": "${workspaceFolder}/test/smoke/test/index.js",
  "cwd": "${workspaceFolder}/test/smoke",
  "timeout": 240000
}

Troubleshooting

Debugger Won't Attach

Ensure watch mode is running: npm run watch
Check that Electron is downloaded: npm run electron
Increase timeout in launch.json
Try running ./scripts/code.sh first

Breakpoints Not Hit

Verify source maps are generated (check out/ directory)
Ensure outFiles in launch.json is correct
Check that breakpoint is in executed code path
Try setting "pauseForSourceMap": true

Can't See Variables

Enable source map support
Check variable scope (may be optimized away)
Try running in non-minified build

Performance Issues

Debug builds are slower. For performance testing:

Build with production settings
Disable source maps temporarily
Use the Performance Profiler instead of debugger

Next Steps

Running Tests

Learn how to run and write tests

Development Workflow

Understand the development process

Building from Source

Review build instructions

Chrome DevTools

Learn Chrome DevTools features

Getting Started

Core Concepts

Development

Architecture

Extensions

Workbench

Contributing

Overview

Quick Start

Debug Configurations

Main Configurations

Process-Specific Debugging

Extension Host

Shared Process

Search Process

Pty Host Process

Debugging Specific Components

Built-in Extensions

Unit Tests

Web Development

Advanced Debugging Techniques

Debugging with Source Maps

Debugging Observables

Debugging Native Modules

Remote Debugging

Debugging Tips

Debugging Smoke Tests

Troubleshooting

Next Steps

Running Tests

Development Workflow

Building from Source

Chrome DevTools

​Overview

​Quick Start

​Debug Configurations

​Main Configurations

​Process-Specific Debugging

Extension Host

Shared Process

Search Process

Pty Host Process

​Debugging Specific Components

​Built-in Extensions

​Unit Tests

​Web Development

​Advanced Debugging Techniques

​Debugging with Source Maps

​Debugging Observables

​Debugging Native Modules

​Remote Debugging

​Debugging Tips

​Debugging Smoke Tests

​Troubleshooting

​Next Steps

Running Tests

Development Workflow

Building from Source

Chrome DevTools

Overview

Quick Start

Debug Configurations

Main Configurations

Process-Specific Debugging

Debugging Specific Components

Built-in Extensions

Unit Tests

Web Development

Advanced Debugging Techniques

Debugging with Source Maps

Debugging Observables

Debugging Native Modules

Remote Debugging

Debugging Tips

Debugging Smoke Tests

Troubleshooting

Next Steps