{"record":{"id":"6029cbf954842be8","repo":"go-delve/delve","slug":"native-backend-disabled-during-compilation","errorCode":null,"errorMessage":"native backend disabled during compilation","messagePattern":"native backend disabled during compilation","errorType":"error_code","errorClass":"ErrNativeBackendDisabled","httpStatus":null,"severity":"critical","filePath":"pkg/proc/native/nonative_darwin.go","lineNumber":14,"sourceCode":"//go:build darwin && !macnative\n\npackage native\n\nimport (\n\t\"errors\"\n\n\t\"github.com/go-delve/delve/pkg/dwarf/op\"\n\t\"github.com/go-delve/delve/pkg/proc\"\n\t\"github.com/go-delve/delve/pkg/proc/amd64util\"\n\t\"github.com/go-delve/delve/pkg/proc/internal/ebpf\"\n)\n\nvar ErrNativeBackendDisabled = errors.New(\"native backend disabled during compilation\")\n\n// Launch returns ErrNativeBackendDisabled.\nfunc Launch(_ []string, _ string, _ proc.LaunchFlags, _ []string, _ string, _ string, _ proc.OutputRedirect, _ proc.OutputRedirect) (*proc.TargetGroup, error) {\n\treturn nil, ErrNativeBackendDisabled\n}\n\n// Attach returns ErrNativeBackendDisabled.\nfunc Attach(_ int, _ *proc.WaitFor, _ []string) (*proc.TargetGroup, error) {\n\treturn nil, ErrNativeBackendDisabled\n}\n\nfunc waitForSearchProcess(string, map[int]struct{}) (int, error) {\n\treturn 0, proc.ErrWaitForNotImplemented\n}\n\n// waitStatus is a synonym for the platform-specific WaitStatus\ntype waitStatus struct{}\n","sourceCodeStart":1,"sourceCodeEnd":32,"githubUrl":"https://github.com/go-delve/delve/blob/a23773e6c31361e43246bc43a424ee009679b174/pkg/proc/native/nonative_darwin.go#L1-L32","documentation":"On macOS, Delve's native backend is disabled at compile time (no cgo/debugserver integration in this build), so ErrNativeBackendDisabled is returned by every entry point: Launch, Attach, killProcess, registers, requestManualStop and resume. It signals that the native debugger cannot operate in this binary at all, not a runtime failure.","triggerScenarios":"dlv debug/attach/exec on macOS with a binary built without the native backend (built without cgo or with the nonative_darwin build tag); any later call into registers/resume/kill on such a process object.","commonSituations":"Installing delve with CGO_ENABLED=0 on macOS; cross-compiling dlv for darwin from Linux; CI builds that strip cgo; downloading a dlv artifact compiled with the native backend stubbed out.","solutions":["Rebuild/install delve on macOS with cgo enabled: CGO_ENABLED=1 go install github.com/go-delve/delve/cmd/dlv@latest","Do not set the 'nonativebackend' build tag when building for macOS","Use an official release binary of dlv for darwin rather than a self-built/cross-compiled one","On macOS without native backend support, use the CoreDump backend or lldb-based alternatives instead"],"exampleFix":"// before (macOS)\nCGO_ENABLED=0 go install github.com/go-delve/delve/cmd/dlv@latest\n// after\nCGO_ENABLED=1 go install github.com/go-delve/delve/cmd/dlv@latest","handlingStrategy":"validation","validationCode":"// detect a delve build without the native backend before attempting to debug\nfunc nativeBackendAvailable() bool {\n    // go-delve exposes this at build time; in-process, check cgo and GOOS\n    return runtime.GOOS != \"darwin\" || build.Default.CgoEnabled\n}","typeGuard":null,"tryCatchPattern":"tg, err := debugger.Attach(pid, \"\")\nif err != nil {\n    if errors.Is(err, native.ErrNativeBackendDisabled) || strings.Contains(err.Error(), \"native backend disabled\") {\n        return fmt.Errorf(\"this dlv binary was built without the native backend; rebuild with CGO_ENABLED=1\")\n    }\n    return err\n}","preventionTips":["On macOS always build/install delve with cgo enabled (CGO_ENABLED=1)","Never set the 'nonativebackend' build tag for darwin builds","Prefer official dlv release binaries over custom/cross-compiled artifacts","Verify `dlv version` and build info when native debugging unexpectedly fails"],"tags":["macos","cgo","build-tags","native-backend"],"backgroundTag":"native-backend-disabled-at-build","analyzedSha":"a23773e6c31361e43246bc43a424ee009679b174","analyzedAt":"2026-08-31T15:12:45.221Z","schemaVersion":2},"datasetVersion":"2026-08-31T19:17:28.585Z"}