The Go extension historically used a small adapter program to work with the Go debugger, Delve. The extension transitioned to communicate with Delve directly but there are still cases you may need to use the legacy debug adapter (e.g. remote debugging). This document explains how to use the legacy debug adapter.

• Set up
  • Installation
  • Configuration
• Launch Configurations
  • Specifying build tags
  • Specifying other build flags
  • Using VS Code Variables
  • Snippets
• Debugging on Windows Subsystem for Linux (WSL)
• Remote Debugging
• Troubleshooting
  • Read documentation and common issues
  • Update Delve
  • Check for multiple versions of Delve
  • Check your launch configuration
  • Check your GOPATH
  • Enable logging
  • Optional: Debug the debugger
  • Ask for help
• Common issues

Delve (dlv) should be installed by default when you install this extension. You may need to update dlv to the latest version to support the latest version of Go. To install or update dlv, open the Command Palette (Windows/Linux: Ctrl+Shift+P; OSX: Shift+Command+P), select Go: Install/Update Tools, and select dlv.

To opt in to use the legacy debug adapter (legacy) by default, add the following in your VSCode settings.json.

    "go.delveConfig": {
        "debugAdapter": "legacy",
    }

If you want to use the legacy mode for only a subset of your launch configurations, you can use the debugAdapter attribute to switch between "dlv-dap" and "legacy" mode. For Remote Debugging (launch configuration with "mode": "remote" attribute), the extension will use the "legacy" mode by default, so setting this attribute won't be necessary.

Throughout this document, we assume that you opted in to use the legacy debug adapter. For debugging using the new debug adapter (default, "dlv-dap" mode), please see the documentation about Debugging.

You may not need to configure any settings to start debugging your programs, but you should be aware that the debugger looks at the following settings.

• Related to GOPATH:
  • go.gopath
  • go.inferGopath
• go.delveConfig
  • apiVersion: Controls the version of the Delve API used (default: 2).
  • dlvLoadConfig: The configuration passed to Delve, which controls how variables are shown in the Debug pane. Not applicable when apiVersion is 1.
    • maxStringLen: Maximum number of bytes read from a string (default: 64).
    • maxArrayValues: Maximum number of elements read from an array, slice, or map (default: 64).
    • maxStructFields: Maximum number of fields read from a struct. A setting of -1 indicates that all fields should be read (default: -1).
    • maxVariableRecurse: How far to recurse when evaluating nested types (default: 1).
    • followPointers: Automatically dereference pointers (default: true).
  • showGlobalVariables: Show global variables in the Debug view (default: false).
  • debugAdapter: Controls which debug adapter to use (default: legacy).
  • substitutePath: Path mappings to apply to get from a path in the editor to a path in the compiled program (default: []).

There are some common cases when you might want to tweak the Delve configurations.

• To change the default cap of 64 on string and array length when inspecting variables in the Debug view, set maxStringLen. (See a related known issue: golang/vscode-go#126).
• To evaluate nested variables in the Run view, set maxVariableRecurse.

To get started debugging, run the command Debug: Open launch.json. If you did not already have a launch.json file for your project, this will create one for you. It will contain this default configuration, which can be used to debug the current package. With mode auto, the file that is currently open will determine whether to debug the program as a test. If program is instead set to a Go file, that file will determine which mode to run in.

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Launch",
            "type": "go",
            "request": "launch",
            "mode": "auto",
            "program": "${fileDirname}",
            "debugAdapter": "legacy",
            "env": {},
            "args": []
        }
    ]
}

There are some more properties that you can adjust in the debug configuration:

If your program contains build tags, you can use the buildFlags property. For example, if you build your code with:

go build -tags=whatever

Then, set:

"buildFlags": "-tags=whatever"

in your launch configuration. This property supports multiple tags, which you can set by using single quotes. For example:

"buildFlags": "-tags='first,second,third'"

The flags specified in buildFlags and env.GOFLAGS are passed to the Go compiler when building your program for debugging. Delve adds -gcflags=all="-N -l" to the list of build flags to disable optimizations. User specified buildFlags conflict with this setting, so the extension removes them (Issue #117). If you wish to debug a program using custom -gcflags, build the program using go build and launch using exec mode:

{
    "name": "Launch executable",
    "type": "go",
    "request": "launch",
    "mode": "exec",
    "program": "/absolute/path/to/executable"
}

Note that it is not recommended to debug optimized executables as Delve may not have the information necessary to properly debug your program.

Any property in the launch configuration that requires a file path can be specified in terms of VS Code variables. Here are some useful ones to know:

• ${workspaceFolder} refers to the root of the workspace opened in VS Code. If using a multi root workspace, you must specify the folder name ${workspaceFolder:folderName}
• ${fileWorkspaceFolder} refers to the the current opened file's workspace folder.
• ${file} refers to the currently opened file.
• ${fileDirname} refers to the directory containing the currently opened file. This is typically also the name of the Go package containing this file, and as such, can be used to debug the currently opened package.

In addition to VS Code variables, you can make use of snippets when editing the launch configuration in launch.json.

When you type go in the launch.json file, you will see snippet suggestions for debugging the current file or package or a given test function.

Below are the available sample configurations:

Recall that ${file} refers to the currently opened file (see Using VS Code Variables). For debugging a package that consists with multiple files, use ${fileDirname} instead.

{
    "name": "Launch file",
    "type": "go",
    "request": "launch",
    "mode": "auto",
    "program": "${file}"
}

Recall that ${workspaceFolder} refers to the current workspace (see Using VS Code Variables). You will need to manually specify the function name instead of "MyTestFunction".

{
    "name": "Launch test function",
    "type": "go",
    "request": "launch",
    "mode": "test",
    "program": "${workspaceFolder}",
    "args": [
        "-test.run",
        "MyTestFunction"
    ]
}

A package is a collection of source files in the same directory that are compiled together. Recall that ${fileDirname} refers to the directory of the open file (see Using VS Code Variables).

{
    "name": "Launch test package",
    "type": "go",
    "request": "launch",
    "mode": "test",
    "program": "${workspaceFolder}"
}

Substitute processName with the name of the local process.

{
    "name": "Attach to local process",
    "type": "go",
    "request": "attach",
    "mode": "local",
    "processId": "processName"
}

{
    "name": "Connect to server",
    "type": "go",
    "request": "attach",
    "mode": "remote",
    "remotePath": "${workspaceFolder}",
    "port": 2345,
    "host": "127.0.0.1"
}

There is no snippet suggestion for this configuration.

{
    "name": "Launch executable",
    "type": "go",
    "request": "launch",
    "mode": "exec",
    "program": "/absolute/path/to/executable"
}

If passing arguments to or calling subcommands and flags from a binary, the args property can be used.

{
    "name": "Launch executable",
    "type": "go",
    "request": "launch",
    "mode": "exec",
    "program": "/absolute/path/to/executable",
    "args": ["subcommand", "arg", "--flag"],
}

If you are using using WSL, you will need the WSL 2 Linux kernel. See WSL 2 Installation and note the Window 10 build version requirements.

To debug on a remote machine, you must first run a headless Delve server on the target machine. The examples below assume that you are in the same folder as the package you want to debug. If not, please refer to the dlv debug documentation.

To start the headless Delve server:

dlv debug --headless --listen=:2345 --log --api-version=2

Any arguments that you want to pass to the program you are debugging must also be passed to this Delve server. For example:

dlv debug --headless --listen=:2345 --log -- -myArg=123

Then, create a remote debug configuration in your launch.json.

{
    "name": "Launch remote",
    "type": "go",
    "request": "attach",
    "mode": "remote",
    "remotePath": "/absolute/path/dir/on/remote/machine",
    "port": 2345,
    "host": "127.0.0.1",
    "cwd": "/absolute/path/dir/on/local/machine",
}

In the example, the VS Code debugger will run on the same machine as the headless dlv server. Make sure to update the port and host settings to point to your remote machine.

remotePath should point to the absolute path of the program being debugged in the remote machine. cwd should point to the absolute path of the working directory of the program being debugged on your local machine. This should be the counterpart of the folder in remotePath. See golang/vscode-go#45 for updates regarding remotePath and cwd. You can also use the equivalent substitutePath configuration.

{
    "name": "Launch remote",
    "type": "go",
    "request": "attach",
    "mode": "remote",
    "substitutePath": [
		{
			"from": "/absolute/path/dir/on/local/machine",
			"to": "/absolute/path/dir/on/remote/machine",
		},
	],
    "port": 2345,
    "host": "127.0.0.1",
    "cwd": "/absolute/path/dir/on/local/machine",
}

If you do not set, remotePath or substitutePath, then the debug adapter will attempt to infer the path mappings. See golang/vscode-go#45 for more information.

When you run the Launch remote target, VS Code will send debugging commands to the dlv server you started, instead of launching it's own dlv instance against your program.

For further examples, see this launch configuration for a process running in a Docker host.

Debugging is one of the most complex features offered by this extension. The features are not complete, and a new implementation is currently being developed (see golang/vscode-go#23).

The suggestions below are intended to help you troubleshoot any problems you encounter. If you are unable to resolve the issue, please take a look at the current known debugging issues or file a new issue.

Start by taking a quick glance at the common issues described below. You can also check the Delve FAQ in case the problem is mentioned there.

If the problem persists, it's time to start troubleshooting. A good first step is to make sure that you are working with the latest version of Delve. You can do this by running the Go: Install/Update Tools command and selecting dlv.

Next, confirm that your launch configuration is correct.

One common error is could not launch process: stat ***/debug.test: no such file or directory. You may see this while running in the test mode. This happens when the program attribute points to a folder with no test files, so ensure that the program attribute points to a directory containing the test files you wish to debug.

Also, check the version of the Delve API used in your launch configuration. This is handled by the –api-version flag, 2 is the default. If you are debugging on a remote machine, this is particularly important, as the versions on the local and remote machines much match. You can change the API version by editing the launch.json file.

You might have multiple different versions of dlv installed, and VS Code Go could be using a wrong or old version. Run the Go: Locate Configured Go Tools command and see where VS Code Go has found dlv on your machine. You can try running which dlv to see which version of dlv you are using on the command-line.

To fix the issue, simply delete the version of dlv used by the Go extension. Note that the extension first searches for binaries in your $GOPATH/bin and then looks on your $PATH.

If you see the error message Failed to continue: "Error: spawn EACCES", the issue is probably multiple versions of dlv.

If you notice Unverified breakpoints or missing variables, ensure that your binary was built without compiler optimizations. Try building the binary with -gcflags="all=-N -l".

Make sure that the debugger is using the right GOPATH. This is probably the issue if you see Cannot find package ".." in any of ... errors. Read more about configuring your GOPATH or file an issue report.

As a work-around, add the correct GOPATH as an environment variable in the env property in the launch.json file.

Next, check the logs produced by Delve. These will need to be manually enabled. Follow these steps:

• Set "showLog": true in your launch configuration. This will show Delve logs in the Debug Console pane (Ctrl+Shift+Y).
• Set "trace": "log" in your launch configuration. Again, you will see logs in the Debug Console pane (Ctrl+Shift+Y). These logs will also be saved to a file and the path to this file will be printed at the top of the Debug Console.
• Set "logOutput": "rpc" in your launch configuration. You will see logs of the RPC messages going between VS Code and Delve. Note that for this to work, you must also have set "showLog": true.
  • The logOutput attribute corresponds to the --log-output flag used by Delve. It is a comma-separated list of components that should produce debug output.

See common issues below to decipher error messages you may find in your logs.

With "trace": "log", you will see the actual call being made to dlv. To aid in your investigation, you can copy that and run it in your terminal.

This is not a required step, but if you want to continue digging deeper, you can, in fact, debug the debugger. The code for the debugger can be found in the debug adapter module. See our contribution guide to learn how to run and sideload the Go extension.

At this point, it's time to look at the common issues below or the existing debugging issues on the issue tracker. If that still doesn't solve your problem, file a new issue.

Try running delve debug ./main in the WSL command line and see if you get a prompt.

Solution: Ensure you are running the WSL 2 Kernel, which (as of 4/15/2020) requires an early release of the Windows 10 OS. This is available to anyone via the Windows Insider program. See Debugging on WSL.

The solution this issue differs based on your OS.

This usually happens on OSX due to signing issues. See the discussions in Microsoft/vscode-go#717, Microsoft/vscode-go#269 and go-delve/delve#357.

Solution: You may have to uninstall dlv and install it manually as described in the Delve instructions.

Docker has security settings preventing ptrace(2) operations by default within the container.

Solution: To run your container insecurely, pass --security-opt=seccomp:unconfined to docker run. See go-delve/delve#515 for references.

This error can show up for Mac users using Delve versions 0.12.2 and above. xcode-select --install has solved the problem for a number of users.

Since the debugger and go compiler use the actual filenames, extra configuration is required to debug symlinked directories. Use the substitutePath property to tell the debugAdapter how to properly translate the paths. For example, if your project lives in /path/to/actual/helloWorld, but the project is open in vscode under the linked folder /path/to/hello, you can add the following to your config to set breakpoints in the files in /path/to/hello:

{
    "name": "Launch remote",
    "type": "go",
    "request": "launch",
    "mode": "debug",
    "program": "/path/to/hello",
    "substitutePath": [
		{
			"from": "/path/to/hello",
			"to": "/path/to/actual/helloWorld",
		},
	],
}

This extension does not provide general support for debugging projects containing symlinks. If substitutePath does not meet your needs, please consider commenting on this issue that contains updates to symlink support reference golang/vscode-go#622.

✏️ Want to contribute to this wiki?

Update the source and send a PR.