What causes "software exception" in go-delve/delve?

Inspect the goroutine/thread state and stack at the stop to find which instruction or runtime call raised the exception

software exception

Error message

software exception

What it means

This error comes from machTargetExcToError, which maps Mach exception codes reported by debugserver/lldb-server (on macOS) into Go errors. Mach exception 0x95 (EXC_SOFTWARE) means the target process raised a software-generated exception that is not a breakpoint or arithmetic fault. Delve surfaces it as a stop reason so the user knows the debuggee hit an abnormal condition.

Source

Thrown at pkg/proc/gdbserial/gdbserver.go:2233

}

func registerName(arch *proc.Arch, regNum uint64) string {
	regName, _, _ := arch.DwarfRegisterToString(int(regNum), nil)
	return strings.ToLower(regName)
}

func machTargetExcToError(sig uint8) error {
	switch sig {
	case 0x91:
		return errors.New("bad access")
	case 0x92:
		return errors.New("bad instruction")
	case 0x93:
		return errors.New("arithmetic exception")
	case 0x94:
		return errors.New("emulation exception")
	case 0x95:
		return errors.New("software exception")
	case 0x96:
		return errors.New("breakpoint exception")
	}
	return nil
}

func checkRosettaExpensive() error {
	if runtime.GOOS != "darwin" {
		return nil
	}
	if runtime.GOARCH != "arm64" {
		return nil
	}

	// Additionally check the output of 'uname -m' if it's x86_64 it means that
	// the shell we are running on is being emulated by Rosetta even though our
	// process isn't. In this condition debugserver will crash.
	out, err := exec.Command("uname", "-m").Output()

View on GitHub (pinned to a23773e6c3)

Solutions

Inspect the goroutine/thread state and stack at the stop to find which instruction or runtime call raised the exception
Check whether the binary was built for the correct GOARCH/OS matching the host (avoid Rosetta-translated binaries)
If the exception is intentional (e.g. signal via software exception), handle or filter it in the debugger session
Update debugserver/Xcode command line tools; older debugserver versions report spurious Mach exceptions

Defensive patterns

Strategy: try-catch

Try / catch

if err := dlvTrace(ctx); err != nil {
    if strings.Contains(err.Error(), "software exception") {
        // inspect stop state: which thread/goroutine, current instruction
        log.Printf("target raised EXC_SOFTWARE: %v", err)
    }
}

Prevention

Build the debuggee for the native macOS architecture (avoid Rosetta-translated binaries)
Keep debugserver/Xcode CLT up to date
Avoid running multiple debuggers on the same process

When it happens

Trigger: Debugging a Go program on macOS via the gdbserial backend (debugserver/lldb-server); the process receives a Mach EXC_SOFTWARE (0x95) during resume/single-step, e.g. from an explicit software abort or unsupported instruction trap.

Common situations: Debugging on macOS when the target hits a software trap not recognized as a breakpoint (e.g. deliberate EXC_SOFT_SIGNAL, unusual runtime traps); running under mismatched tooling or on architectures where instructions fault as EXC_SOFTWARE; attaching to processes that raise software exceptions intentionally.

Related errors

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