How To Debug Go Code with Visual Studio Code

By the end of this tutorial you will be able to set breakpoints, step through Go code, inspect variables, and debug tests in Visual Studio Code using the Go extension and Delve.

You will install the Go extension and Delve (or use the extension’s automatic install), create a launch.json configuration, then run through breakpoints, conditional breakpoints, and debugging a test function.

To complete this tutorial, you need:

• Basic knowledge of Go. For more, see the How To Code in Go series.
• Visual Studio Code installed.
• The Go extension for VS Code installed.

• Install the Go extension for VS Code and Delve (manually with go install github.com/go-delve/delve/cmd/dlv@latest or via the extension’s first-run prompt).
• Use a full launch.json with "program":"${workspaceFolder}" and "configurations" (plural). Avoid deprecated "${workspaceRoot}" and single-file-only "${fileDirname}" for multi-package projects.
• Set breakpoints in the gutter, use F5 to continue and F10 / F11 / Shift+F11 to step over, into, or out. Use the Watch panel for expressions.
• Conditional breakpoints stop only when their expression is true; use Edit Breakpoint to add a condition.
• For tests, use debug test above the test function; the same Delve backend runs both application and test debugging.

Open any .go file in VS Code. The status bar may prompt you to Install Analysis Tools. Click that link to install the Go packages the extension needs.

Delve is the debugger the Go extension uses. Go’s default go run does not keep the symbol table and line information needed for interactive debugging, so Delve is required for breakpoints and stepping.

You can install Delve in two ways.

Option A: Let the Go extension install Delve

When you start a debug session (e.g., press F5) for the first time without dlv in your PATH, the Go extension can prompt you to install Delve. Accept the prompt; it will run the install and place the dlv binary in your Go bin directory.

Option B: Install Delve manually

Run:

go install github.com/go-delve/delve/cmd/dlv@latest

When downloading, you may see output similar to:

go: downloading github.com/go-delve/delve v1.x.x
go: downloading github.com/some/dependency v0.x.x

On a cached or already-installed system, go install produces no output on success.

Verify installation:

dlv version

Delve version: 1.x.x

Ensure $GOPATH/bin or $HOME/go/bin is in your PATH so the dlv command is found. For platform-specific steps, see Delve installation.

This section uses two examples: a Go program that outputs JSON, and a test you will debug in VS Code.

Create a file main.go:

nano main.go

Add the following content:

package main

import (
    "encoding/json"
    "fmt"
    "log"
)

// Avenger represents a single hero
type Avenger struct {
    RealName string `json:"real_name"`
    HeroName string `json:"hero_name"`
    Planet   string `json:"planet"`
    Alive    bool   `json:"alive"`
}

func (a *Avenger) isAlive() {
    a.Alive = true
}

func main() {
    avengers := []Avenger{
        {
            RealName: "Dr. Bruce Banner",
            HeroName: "Hulk",
            Planet:   "Midgard",
        },
        {
            RealName: "Tony Stark",
            HeroName: "Iron Man",
            Planet:   "Midgard",
        },
        {
            RealName: "Thor Odinson",
            HeroName: "Thor",
            Planet:   "Midgard",
        },
    }

    avengers[1].isAlive()

    jsonBytes, err := json.Marshal(avengers)
    if err != nil {
        log.Fatalln(err)
    }
    fmt.Println(string(jsonBytes))
}

The code defines an Avenger struct, builds a slice, marks one Avenger as alive, marshals to JSON, and prints it.

Run the app:

go run main.go

[{"real_name":"Dr. Bruce Banner","hero_name":"Hulk","planet":"Midgard","alive":false},{"real_name":"Tony Stark","hero_name":"Iron Man","planet":"Midgard","alive":true},{"real_name":"Thor Odinson","hero_name":"Thor","planet":"Midgard","alive":false}]

To debug, you need a launch configuration. In the left sidebar, click the Run and Debug (bug) icon, then click the gear icon to create a configuration.

A .vscode/launch.json file is created. Use a full configuration so the debugger targets your workspace correctly.

Replace the contents of .vscode/launch.json with this complete scaffold:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Launch",
      "type": "go",
      "request": "launch",
      "mode": "auto",
      "program": "${workspaceFolder}",
      "env": {},
      "args": [],
      "showLog": true,
      "console": "integratedTerminal"
    }
  ]
}

Add a breakpoint on line 21 (func main()) by clicking in the gutter to the left of the line number. A red dot appears.

Press F5 or click the green Launch button in the Run and Debug view to start debugging.

Click Step Over on the debug toolbar (or press F10) repeatedly. Execution advances one line at a time and eventually reaches line 40.

The Run and Debug sidebar shows the state at the current line: variables and call stack.

In Variables you see the values at that point. The call stack shows the current function (main) and line. As you keep stepping, you can confirm that after the relevant line, avengers[1] (Tony Stark) has Alive set to true.

Use the toolbar or shortcuts to control execution:

Step Over runs the current line without entering function calls. Step Into stops inside the function invoked on that line (e.g., avengers[1].isAlive()). Step Out runs until the current function returns.

The Watch panel evaluates expressions each time execution pauses. Use it to track specific values without scrolling Variables.

To add a watch: open the Watch section in the Run and Debug sidebar, click +, and enter an expression. For example, while paused in main with avengers in scope, add:

avengers[1].Alive

As you step, the Watch panel shows the current value (e.g., false before avengers[1].isAlive() and true after). You can add any valid Go expression that is in scope at the current frame.

Conditional breakpoints only stop when a given expression is true. Right-click in the gutter next to a line and choose Edit Breakpoint (or Add Conditional Breakpoint if there is no breakpoint yet).

On line 40 (avengers[1].isAlive()), add a condition such as avengers[1].Planet == "Earth".

Launch with F5. The program runs without stopping at that breakpoint because the condition is false (planet is "Midgard"). Output appears in the Debug Console.

Change Tony Stark’s planet to "Earth" in main.go:

{
    RealName: "Tony Stark",
    HeroName: "Iron Man",
    Planet:   "Earth",
},

Run the debugger again with F5. Execution stops at the conditional breakpoint and the JSON output is not yet printed in the Debug Console.

You can run and debug Go tests from the editor. Add a helper and a test in the same package.

Add this function to main.go:

func add(a, b int) int {
    return a + b
}

Create main_test.go in the same directory:

package main

import "testing"

func Test_add(t *testing.T) {
    a, b, c := 1, 2, 3

    res := add(a, b)

    if res != c {
        t.Fail()
    }
}

With the Go extension installed, you see run test and debug test above the test function.

Click run test to run the test and see results in the Output panel. To debug, add a breakpoint on line 10 (if res != c) and click debug test. The debugger starts and you can step and inspect variables as in the main program.

1. Delve Not Found

If you encounter the error message: could not launch process: exec: "dlv": executable file not found in $PATH it means the dlv binary is not available in your PATH. To fix this, add the directory where Go installs binaries ($GOPATH/bin or $HOME/go/bin) to your PATH. On Unix-like systems, you can add the following line to your shell profile:

export PATH=$PATH:$(go env GOPATH)/bin

2. Breakpoint Not Binding (Gray or Hollow Circle)

A gray or hollow breakpoint icon generally means that the running binary was not built with debugging symbols. Make sure your launch.json configuration includes "mode": "auto" so that the extension compiles your code with symbols. Avoid attaching to binaries built with go build unless you used -gcflags="all=-N -l" to include debug info, and always run your code through the debugger for breakpoints to work.

3. F5 Starts Then Exits Immediately

If pressing F5 (Start Debugging) causes the program to start and then exit immediately, check the "program" path in your launch.json. It should point to a directory containing main.go (or your main package), not to a single file. Use "${workspaceFolder}" if main.go is at the workspace root, or specify a directory like "${workspaceFolder}/cmd/myapp" if your main package is inside a subdirectory.

Do I need to install Delve separately if I use the Go extension?

You can install Delve yourself with go install github.com/go-delve/delve/cmd/dlv@latest and ensure dlv is on your PATH. Alternatively, the Go extension can install Delve when you first start a debug session (F5) if it detects that dlv is missing.

Can I debug Go tests without the VS Code Go extension?

Yes. You can run Delve from the terminal, for example: dlv test -- -test.run Test_add. The Go extension adds the debug test button and integrates the same Delve backend into the VS Code UI.

What is the difference between dlv debug and VS Code’s debugger?

dlv debug is the command-line interface to Delve. VS Code’s Go debugger uses Delve under the hood and talks to it via the DAP (Debug Adapter Protocol). The behavior (breakpoints, stepping, variable inspection) is the same; VS Code provides the UI and keybindings.

Why does my breakpoint appear as a hollow circle instead of a solid red dot?

A hollow or gray breakpoint means it is not yet bound. Common causes: the binary was built without debug symbols (e.g., an optimized release build), or the debug session has not started. Use "mode": "auto" in launch.json so the extension builds with debug info, and start the session with F5.

You configured the Go extension and Delve, created a launch.json, and used breakpoints, stepping, the Watch panel, and conditional breakpoints to debug a sample app and a test. The same Delve engine is available from the terminal via dlv debug for environments without a GUI; see Delve CLI usage for command-line options.