go-delve/delve · error · errMacOSBackendUnavailable

debugserver or lldb-server not found: install Xcode's comman

Error message

debugserver or lldb-server not found: install Xcode's command line tools or lldb-server

What it means

This error is returned when launching or attaching via the gdbserial backend on macOS fails because the backend executable (debugserver or lldb-server) cannot be found. Delve on macOS relies on Apple's debugserver (shipped with Xcode command line tools) or an lldb-server binary to drive the debuggee. betterGdbserialLaunchError replaces the generic ErrBackendUnavailable with this actionable message when running on darwin.

Source

Thrown at service/debugger/debugger.go:390

// Attach will attach to the process specified by 'pid'.
func (d *Debugger) Attach(pid int, path string, waitFor *proc.WaitFor) (*proc.TargetGroup, error) {
	switch d.config.Backend {
	case "native":
		return native.Attach(pid, waitFor, d.config.DebugInfoDirectories)
	case "lldb":
		return betterGdbserialLaunchError(gdbserial.LLDBAttach(pid, path, waitFor, d.config.DebugInfoDirectories))
	case "default":
		if runtime.GOOS == "darwin" {
			return betterGdbserialLaunchError(gdbserial.LLDBAttach(pid, path, waitFor, d.config.DebugInfoDirectories))
		}
		return native.Attach(pid, waitFor, d.config.DebugInfoDirectories)
	default:
		return nil, fmt.Errorf("unknown backend %q", d.config.Backend)
	}
}

var errMacOSBackendUnavailable = errors.New("debugserver or lldb-server not found: install Xcode's command line tools or lldb-server")

func betterGdbserialLaunchError(p *proc.TargetGroup, err error) (*proc.TargetGroup, error) {
	if runtime.GOOS != "darwin" {
		return p, err
	}
	if !errors.Is(err, &gdbserial.ErrBackendUnavailable{}) {
		return p, err
	}

	return p, errMacOSBackendUnavailable
}

// ProcessPid returns the PID of the process
// the debugger is debugging.
func (d *Debugger) ProcessPid() int {
	d.targetMutex.Lock()
	defer d.targetMutex.Unlock()
	return d.target.Selected.Pid()

View on GitHub (pinned to a23773e6c3)

Solutions

1. Install Xcode's command line tools: run `xcode-select --install`
2. Install full Xcode and ensure its debugserver is available, or build and put lldb-server on PATH
3. If using a custom debugserver path, set the DELVE_SERVER_LOCATION environment variable to a valid debugserver/lldb-server path
4. Verify with `xcrun -f debugserver` or `which lldb-server` that a backend binary exists

Example fix

// before (shell, missing backend)
dlv exec ./app  // fails: debugserver or lldb-server not found
// after
xcode-select --install
xcrun -f debugserver  # confirm binary exists
dlv exec ./app

// shell check before launching on darwin
if runtime.GOOS == "darwin" {
    if _, err := exec.LookPath("debugserver"); err != nil {
        if _, err2 := exec.LookPath("lldb-server"); err2 != nil && os.Getenv("DELVE_SERVER_LOCATION") == "" {
            return errors.New("run: xcode-select --install")
        }
    }
}

func backendAvailable() bool {
    if os.Getenv("DELVE_SERVER_LOCATION") != "" { return true }
    a, _ := exec.LookPath("debugserver"); b, _ := exec.LookPath("lldb-server")
    return a != "" || b != ""
}

tg, err := dbg.Launch(args, "")
var unavailable *gdbserial.ErrBackendUnavailable
if errors.As(err, &unavailable) || strings.Contains(fmt.Sprint(err), "debugserver or lldb-server not found") {
    // guide user to install Xcode CLT / lldb-server and retry
}

When it happens

Trigger: Calling debugger launch/attach APIs (CreateProcess via d.Launch or d.Attach) with d.config.Backend == "default" or "lldb" on macOS when neither debugserver (from Xcode CLT) nor lldb-server is present in PATH or at the expected paths and the underlying gdbserial.ErrBackendUnavailable error is wrapped.

Common situations: Fresh macOS machines without Xcode command line tools installed; developers who installed only bare Xcode CLT minus lldb; users with a custom DELVE_SERVER_LOCATION that points to a missing binary; CI runners with minimal macOS images lacking Xcode.

Related errors

• stub exited while waiting for connection: %v
• could not connect
• bad access
• bad instruction
• emulation exception

AI-assisted analysis of go-delve/delve@a23773e6c3 (2026-08-31). Data as JSON: /api/errors/1474b9359dbb9e20. Report an issue: GitHub.