GoLand Delve debugging for local Go apps: SDK setup, config and limits

The useful takeaway for local Go debugging in GoLand

Breakpoints miss and variables look wrong in GoLand when the Go SDK, module root and working directory used by the Run/Debug configuration do not match what Delve sees. When they align, GoLand invokes Delve under the hood, launches the target binary under the debugger, and maps source files via the selected SDK and module root. That mapping is the mechanism that makes stepping and inspection work.

How GoLand uses Delve for local apps

Delve is the Go debugger. GoLand does not debug Go code directly; it creates a Run/Debug configuration, selects a Go SDK, and starts dlv with parameters that point to the module root and working directory. The IDE then renders Delve events as breakpoints, stack frames and variable views.

Delve version compatibility is tied to the Go SDK. A mismatch between the SDK used to build and the Delve binary GoLand picks can cause launch failures or incorrect stack traces. GoLand attempts to detect a suitable Delve for the selected SDK, but the SDK must be valid and active for the project.

Worked configuration for a local main package

A minimal example is a module with a main package. The goal is to verify source mapping and breakpoint binding. The settings paths below reflect recent GoLand releases; exact labels can vary between versions.

// main.go
package main

import "fmt"

func main() {
    x := 42
    fmt.Println("value:", x)
}

Configure the project so GoLand can resolve the module.

SDK and project settings

• Open Settings > Go > GOROOT and SDKs. Confirm a valid Go SDK is selected and Delve is detected for that SDK.
• Open Settings > Go > GOPATH. For module mode, ensure Go modules is enabled and the module root is recognized. The module root is the directory containing go.mod.
• Open the project view and verify the module is loaded; imports should resolve without red highlights.

Run/Debug configuration

• Run > Edit Configurations. Add a Go Build configuration.
• Set Go SDK to the SDK you verified above.
• Set Working directory to the module root, not a subdirectory.
• Set Debugger to Delve. Leave the default Delve path unless you need a specific binary.
• Set Environment variables if the program requires them. Do not change the working directory to a path outside the module without adjusting import paths.

Place a breakpoint on the fmt.Println line. Start the configuration in Debug mode. The Run tool window shows the dlv launch command and parameters. Check that the launch references the correct binary path and working directory. In the Debug tool window, the breakpoint should bind and the Variables view should be populated when execution pauses.

Where debugging works reliably

Pure Go code with go.mod aware module roots works reliably. Build tags are respected when the Run configuration uses the same tags as the build. The IDE resolves imports and working directory automatically when the SDK and GOPATH/GOMOD settings are correct.

Limitations and practical constraints

cgo and native code

Debugging cgo-heavy binaries requires CGO enabled and an appropriate C toolchain. GoLand may fail to step into C sources and variable inspection can be incomplete. This is a Delve limitation, not an IDE bug.

Build constraints and generated files

Inconsistent behavior can occur with build constraints or generated files where source on disk does not match the compiled binary. If files are generated during build, ensure the generation step runs before the debugger starts, or debug the generated output directly.

Performance with many goroutines

Large codebases with many goroutines create overhead for Delve. Stepping and variable evaluation can become slow. Limit the scope by using conditional breakpoints and by debugging specific packages.

Dynamic loading and reflect

Heavy use of reflect or dynamically loaded plugins can confuse variable inspection. Delve relies on static type information; dynamic values may appear as <unknown> or be omitted.

Common mistakes

• Wrong Go SDK selected. The SDK used for the Run configuration must match the SDK used to compile. Verify in Settings > Go > GOROOT and SDKs and in the Run configuration.
• Stale dlv binary. Delve compatibility is tied to the SDK, so after upgrading Go, re-check the SDK settings to confirm the debugger is detected for the new SDK.
• Mismatched working directory causing import resolution failures. The working directory should be the module root unless the program explicitly expects another.
• Non-module project without proper GOPATH configuration. For legacy GOPATH projects, set GOPATH correctly and ensure the project root is under $GOPATH/src.

Practical verification

Check the result without assuming success.

• Open Settings > Go > GOROOT and SDKs to confirm a valid Go SDK is selected and Delve is detected.
• Create a simple main.go, add a breakpoint, create a Go run configuration and start in Debug mode to verify breakpoints hit and variables are inspectable.
• Check the Run tool window for dlv launch logs to confirm the debugger process started with expected parameters.
• Test a cgo example to observe step limitations and confirm caution about C source stepping.

Remote or Docker debugging needs matching architecture and exposed ports; local configuration does not transfer automatically. Keep local debugging isolated to the host SDK and module layout described above.