Debugging

This document explains how to debug your Go programs in VS Code. The Go debugger is Delve. You can read more about it in the Delve documentation.

📣 Integration with the Delve’s native DAP implementation is available for preview. Please give it a try and provide feedback!

Overview

• 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

Set up

Delve 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—see Installation below.

Installation

You can also install Delve manually in one of two ways:

1. Open the Command Palette (Windows/Linux: Ctrl+Shift+P; OSX: Shift+Command+P), select Go: Install/Update Tools, and select dlv.
2. Follow the Delve installation instructions.

Start debugging

1. Open the package main source file or the test file you want to debug.

2. Start debugging using one of the following options:

   • Open the Command Palette, select Debug: Start Debugging, then select Go.
   • Open the debug window (Windows/Linux: Ctrl+Shift+D; OSX: Shift+Command+D) and click Run and Debug, then select Go.
   • Select Run > Start Debugging from the main menu.

   See the VS Code Debugging documentation for more information.

Configuration

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.

Launch Configurations

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}",
            "env": {},
            "args": []
        }
    ]
}

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

Specifying build tags

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'"

Specifying other build flags

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.

Using VS Code variables

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.

Snippets

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:

Debug the current file (Go: Launch file)

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}"
}

Debug a single test function (Go: Launch test function)

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"
    ]
}

Debug all tests in the given package (Go: Launch test package)

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}"
}

Attach to a running local process via its process ID (Go: Attach to local process)

Substitute processName with the name of the local process.

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

Attach to a running server (Go: Connect to Server)

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

Debug an existing binary

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"],
}

Debugging on Windows Subsystem for Linux (WSL)

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.

Remote Debugging

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.

Troubleshooting

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.

Read documentation and common issues

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.

Update Delve

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.

Check your launch configuration

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.

Check for multiple versions of Delve

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.

Try building your binary without compiler optimizations

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".

Check your GOPATH

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.

Enable logging

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.

Optional: Debug the debugger

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.

Ask for help

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 or ask a question on the #vscode channel of the Gophers Slack.

Common Issues

delve/launch hangs with no messages on WSL

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.

could not launch process: could not fork/exec

The solution this issue differs based on your OS.

OSX

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.

Linux/Docker

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.

could not launch process: exec: “lldb-server”: executable file not found in $PATH

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.

Debugging symlink directories

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.