The Go extension historically used a small adapter program to work with the Go debugger,Delve.The extension transitioned to communicate withDelve directly but there are still cases you mayneed to use the legacy debug adapter (e.g. remote debugging). This document explains how to use thelegacy 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 updatedlv to the latest version to support the latest versionof Go. To install or updatedlv, open theCommand Palette(Windows/Linux: Ctrl+Shift+P; OSX: Shift+Command+P), selectGo: Install/Update Tools, and selectdlv.

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 usethedebugAdapter attribute to switch between"dlv-dap" and"legacy" mode.ForRemote 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 aboutDebugging.

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 toGOPATH:
  • 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 whenapiVersion 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, setmaxStringLen. (See a related known issue:golang/vscode-go#126).
• To evaluate nested variables in the Run view, setmaxVariableRecurse.

To get started debugging, run the commandDebug: Open launch.json. If you did not already have alaunch.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 modeauto, the file that is currently open will determine whether to debug the program as a test. Ifprogram 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 containsbuild tags, you can use thebuildFlags 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 inbuildFlags andenv.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 usinggo build and launch usingexec 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 ofVS 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 toVS Code variables, you can make use ofsnippets when editing the launch configuration inlaunch.json.

When you typego in thelaunch.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 (seeUsing 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 (seeUsing 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 (seeUsing VS Code Variables).

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

SubstituteprocessName 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, theargs 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. SeeWSL 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 thedlv 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 yourlaunch.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 headlessdlv server. Make sure to update theport andhost 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 inremotePath. Seegolang/vscode-go#45 for updates regardingremotePath andcwd. You can also use the equivalentsubstitutePath 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 orsubstitutePath, then the debug adapter will attempt to infer the path mappings. Seegolang/vscode-go#45 for more information.

When you run theLaunch remote target, VS Code will send debugging commands to thedlv server you started, instead of launching it's owndlv instance against your program.

For further examples, seethis 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 (seegolang/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 thecurrent known debugging issues orfile a new issue.

Start by taking a quick glance at thecommon issues described below. You can also check theDelve 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 theGo: Install/Update Tools command and selectingdlv.

Next, confirm that yourlaunch configuration is correct.

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

Also, check the version of the Delve API used in yourlaunch 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 thelaunch.json file.

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

To fix the issue, simply delete the version ofdlv 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 messageFailed to continue: "Error: spawn EACCES", the issue is probably multiple versions ofdlv.

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

Make sure that the debugger is using the rightGOPATH. This is probably the issue if you seeCannot find package ".." in any of ... errors. Read more about configuring yourGOPATH orfile an issue report.

As a work-around, add the correctGOPATH as an environment variable in theenv property in thelaunch.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.
  • ThelogOutput attribute corresponds to the--log-output flag used by Delve. It is a comma-separated list of components that should produce debug output.

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

With"trace": "log", you will see the actual call being made todlv. 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 thedebug adapter module. See ourcontribution guide to learn how torun andsideload the Go extension.

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

Try runningdelve 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. SeeDebugging on WSL.

The solution this issue differs based on your OS.

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

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

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

Solution: To run your container insecurely, pass--security-opt=seccomp:unconfined todocker run. Seego-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 thesubstitutePath 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. IfsubstitutePath does not meet your needs, please consider commenting on this issue that contains updates to symlink support referencegolang/vscode-go#622.

✏️ Want to contribute to this wiki?

Updatethe source and send a PR.