go-delve/delve · critical · ErrNativeBackendDisabled

native backend disabled during compilation

Error message

native backend disabled during compilation

What it means

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.

Source

Thrown at pkg/proc/native/nonative_darwin.go:14

//go:build darwin && !macnative

package native

import (
	"errors"

	"github.com/go-delve/delve/pkg/dwarf/op"
	"github.com/go-delve/delve/pkg/proc"
	"github.com/go-delve/delve/pkg/proc/amd64util"
	"github.com/go-delve/delve/pkg/proc/internal/ebpf"
)

var ErrNativeBackendDisabled = errors.New("native backend disabled during compilation")

// Launch returns ErrNativeBackendDisabled.
func Launch(_ []string, _ string, _ proc.LaunchFlags, _ []string, _ string, _ string, _ proc.OutputRedirect, _ proc.OutputRedirect) (*proc.TargetGroup, error) {
	return nil, ErrNativeBackendDisabled
}

// Attach returns ErrNativeBackendDisabled.
func Attach(_ int, _ *proc.WaitFor, _ []string) (*proc.TargetGroup, error) {
	return nil, ErrNativeBackendDisabled
}

func waitForSearchProcess(string, map[int]struct{}) (int, error) {
	return 0, proc.ErrWaitForNotImplemented
}

// waitStatus is a synonym for the platform-specific WaitStatus
type waitStatus struct{}

View on GitHub (pinned to a23773e6c3)

Solutions

1. Rebuild/install delve on macOS with cgo enabled: CGO_ENABLED=1 go install github.com/go-delve/delve/cmd/dlv@latest
2. Do not set the 'nonativebackend' build tag when building for macOS
3. Use an official release binary of dlv for darwin rather than a self-built/cross-compiled one
4. On macOS without native backend support, use the CoreDump backend or lldb-based alternatives instead

Example fix

// before (macOS)
CGO_ENABLED=0 go install github.com/go-delve/delve/cmd/dlv@latest
// after
CGO_ENABLED=1 go install github.com/go-delve/delve/cmd/dlv@latest

// detect a delve build without the native backend before attempting to debug
func nativeBackendAvailable() bool {
    // go-delve exposes this at build time; in-process, check cgo and GOOS
    return runtime.GOOS != "darwin" || build.Default.CgoEnabled
}

tg, err := debugger.Attach(pid, "")
if err != nil {
    if errors.Is(err, native.ErrNativeBackendDisabled) || strings.Contains(err.Error(), "native backend disabled") {
        return fmt.Errorf("this dlv binary was built without the native backend; rebuild with CGO_ENABLED=1")
    }
    return err
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• setpgid
• ptrace
• bad access
• bad instruction
• arithmetic exception

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