{"record":{"id":"1474b9359dbb9e20","repo":"go-delve/delve","slug":"debugserver-or-lldb-server-not-found-install-xcod","errorCode":null,"errorMessage":"debugserver or lldb-server not found: install Xcode's command line tools or lldb-server","messagePattern":"debugserver or lldb-server not found: install Xcode's command line tools or lldb-server","errorType":"error_code","errorClass":"errMacOSBackendUnavailable","httpStatus":null,"severity":"error","filePath":"service/debugger/debugger.go","lineNumber":390,"sourceCode":"\n// Attach will attach to the process specified by 'pid'.\nfunc (d *Debugger) Attach(pid int, path string, waitFor *proc.WaitFor) (*proc.TargetGroup, error) {\n\tswitch d.config.Backend {\n\tcase \"native\":\n\t\treturn native.Attach(pid, waitFor, d.config.DebugInfoDirectories)\n\tcase \"lldb\":\n\t\treturn betterGdbserialLaunchError(gdbserial.LLDBAttach(pid, path, waitFor, d.config.DebugInfoDirectories))\n\tcase \"default\":\n\t\tif runtime.GOOS == \"darwin\" {\n\t\t\treturn betterGdbserialLaunchError(gdbserial.LLDBAttach(pid, path, waitFor, d.config.DebugInfoDirectories))\n\t\t}\n\t\treturn native.Attach(pid, waitFor, d.config.DebugInfoDirectories)\n\tdefault:\n\t\treturn nil, fmt.Errorf(\"unknown backend %q\", d.config.Backend)\n\t}\n}\n\nvar errMacOSBackendUnavailable = errors.New(\"debugserver or lldb-server not found: install Xcode's command line tools or lldb-server\")\n\nfunc betterGdbserialLaunchError(p *proc.TargetGroup, err error) (*proc.TargetGroup, error) {\n\tif runtime.GOOS != \"darwin\" {\n\t\treturn p, err\n\t}\n\tif !errors.Is(err, &gdbserial.ErrBackendUnavailable{}) {\n\t\treturn p, err\n\t}\n\n\treturn p, errMacOSBackendUnavailable\n}\n\n// ProcessPid returns the PID of the process\n// the debugger is debugging.\nfunc (d *Debugger) ProcessPid() int {\n\td.targetMutex.Lock()\n\tdefer d.targetMutex.Unlock()\n\treturn d.target.Selected.Pid()","sourceCodeStart":372,"sourceCodeEnd":408,"githubUrl":"https://github.com/go-delve/delve/blob/a23773e6c31361e43246bc43a424ee009679b174/service/debugger/debugger.go#L372-L408","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Install Xcode's command line tools: run `xcode-select --install`","Install full Xcode and ensure its debugserver is available, or build and put lldb-server on PATH","If using a custom debugserver path, set the DELVE_SERVER_LOCATION environment variable to a valid debugserver/lldb-server path","Verify with `xcrun -f debugserver` or `which lldb-server` that a backend binary exists"],"exampleFix":"// before (shell, missing backend)\ndlv exec ./app  // fails: debugserver or lldb-server not found\n// after\nxcode-select --install\nxcrun -f debugserver  # confirm binary exists\ndlv exec ./app","handlingStrategy":"fallback","validationCode":"// shell check before launching on darwin\nif runtime.GOOS == \"darwin\" {\n    if _, err := exec.LookPath(\"debugserver\"); err != nil {\n        if _, err2 := exec.LookPath(\"lldb-server\"); err2 != nil && os.Getenv(\"DELVE_SERVER_LOCATION\") == \"\" {\n            return errors.New(\"run: xcode-select --install\")\n        }\n    }\n}","typeGuard":"func backendAvailable() bool {\n    if os.Getenv(\"DELVE_SERVER_LOCATION\") != \"\" { return true }\n    a, _ := exec.LookPath(\"debugserver\"); b, _ := exec.LookPath(\"lldb-server\")\n    return a != \"\" || b != \"\"\n}","tryCatchPattern":"tg, err := dbg.Launch(args, \"\")\nvar unavailable *gdbserial.ErrBackendUnavailable\nif errors.As(err, &unavailable) || strings.Contains(fmt.Sprint(err), \"debugserver or lldb-server not found\") {\n    // guide user to install Xcode CLT / lldb-server and retry\n}","preventionTips":["Run `xcode-select --install` when provisioning macOS dev machines","Verify `xcrun -f debugserver` in setup scripts before starting debug sessions","Set DELVE_SERVER_LOCATION explicitly in CI so the backend path is deterministic","Keep lldb-server on PATH when using non-Apple toolchains"],"tags":["macos","gdbserial","environment","lldb"],"backgroundTag":"debugger-backend-unavailable","analyzedSha":"a23773e6c31361e43246bc43a424ee009679b174","analyzedAt":"2026-08-31T15:12:45.221Z","schemaVersion":2},"datasetVersion":"2026-08-31T19:17:28.585Z"}