Debugging Go code using VS Code

Install delve

To use the debugger, you must currently manually install delve. See the Installation Instructions for full details. On OS X it requires creating a self-signed cert to sign the dlv binary.

Based on how you install delve it will either end up in your PATH or GOPATH/bin. If dlv binary is in your GOPATH/bin and this GOPATH is not set as an environment variable, then make sure your PATH points to this GOPATH/bin so that the Go extension can find the dlv binary.

Set up configurations in launch.json

Once delve is installed, you can either press F5 or go to the Code debug viewlet and select the configuration gear. If you are using Visual Studio Code 1.8.1 or below, you will see a pop up asking you to select your environment. Select 'Go'.

You will now see a launch.json file created for your workspace, which will contain the configurations for debugging. By default, there would be a single configuration as below:

{
	"version": "0.2.0",
	"configurations": [
		{
			"name": "Launch",
			"type": "go",
			"request": "launch",
			"mode": "debug",
			"remotePath": "",
			"port": 2345,
			"host": "127.0.0.1",
			"program": "${workspaceRoot}",
			"env": {},
			"args": [],
			"showLog": true
		}
	]
}

The program option can refer to a package folder to debug, or a file within that folder. This should be a full path and not relative.

The mode parameter can be set to:

• debug to compile the contents of the program folder and launch under the debugger. [default]
• test to debug tests in the program folder. To debug a single test, pass -test.run and the Test name as args.
• exec to run a pre-built binary specified in program, for example "program":"${workspaceRoot}/mybin".
• remote to attach to a remote headless Delve server. You must manually run Delve on the remote machine, and provide the additional remotePath, host and port debug configuration options pointing at the remote machine.

GOPATH set using the go.gopath setting in Visual Studio Code is not readable by the debugger in the Go extension. Therefore, if you do use the go.gopath setting, remember to pass the same in the env property of the launch.json as an environment variable.

Remote Debugging

To remote debug using VS Code, you must first run a headless Delve server on the target machine. For example:

$ dlv debug --headless --listen=:2345 --log

Then, create a remote debug configuration in VS Code launch.json.

{
	"name": "Remote",
	"type": "go",
	"request": "launch",
	"mode": "remote",
	"remotePath": "${workspaceRoot}",
	"port": 2345,
	"host": "127.0.0.1",
	"program": "${workspaceRoot}",
	"env": {},
	"args": []
}

When you launch the debugger with this new Remote target selected, VS Code will send debugging commands to the dlv server you started previously instead of launching it's own dlv instance against your app.

The above example runs both the headless dlv server and the VS Code debugger locally on the same machine. For an example of running these on different hosts, see the example of debugging a process running in a docker host at https://github.com/lukehoban/webapp-go/tree/debugging.

Troubleshooting

Cannot find Delve debugger at ... Ensure it is in your "GOPATH/bin" or "PATH".

Like the error message says, the extension cannot find dlv. This can happen if dlv got installed to your GOPATH which you have set using go.gopath in the settings. Since the debug adapter cannot read the settings, it is not aware of this GOPATH.

Solution: You can either set the GOPATH as an env var outside VS Code or point PATH to the dlv binary. Another way is to update the env property in launch.json to have GOPATH as a env variable.

Cannot find package ".." in any of ...

If you have set GOPATH using go.gopath in your settings, then the debug adapter cannot read it as the it is not aware of the settings.

Solution: Add the GOPATH as an env var in the env property in the launch.json file.

Failed to continue: "Error: spawn EACCES"

You have dlv running just fine from command line, but VS Code gives this access related error. This can happen if the extension is trying to run the dlv binary from a wrong location. The Go extension first tries to find dlv in your $GOPATH/bin and then in your $PATH.

Solution: Run which dlv in the command line. If this doesnt match your GOPATH/bin, then delete the dlv file in your GOPATH/bin

could not launch process: stat ***/debug.test: no such file or directory

You may see this in the debug console, while trying to run in the test mode. This happens when the program attribute points to a folder with no test files.

Solution: Ensure that the program attribute points to the folder that contains the test files you want to run.

could not launch process: could not fork/exec

This usually happens in OSX due to signing issues. See the discussions in please see #717, #269 and derekparker/delve/357

Solution: You may have to uninstall dlv and install it manually as per instructions