What causes "unknown backend %q" in go-delve/delve?

Check the backend value passed in Config.Backend / the --backend flag; correct it to one of "default", "native", "lldb", or "rr".

go-delve/delve · error

unknown backend %q

Error message

unknown backend %q

What it means

Delve's Launch dispatches on config.Backend ("native", "lldb", "rr", or "default"). When the configured backend string does not match any supported backend case, Launch returns this error instead of starting the debuggee. It means the client selected a backend name Delve does not recognize on this platform.

Source

Thrown at service/debugger/debugger.go:342

			d.recordingDone()
			d.target = grp
			if err := d.checkGoVersion(); err != nil {
				d.log.Error(err)
				err := d.target.Detach(true)
				if err != nil {
					d.log.Errorf("Error detaching from target: %v", err)
				}
			}
		}()
		return nil, nil

	case "default":
		if runtime.GOOS == "darwin" {
			return betterGdbserialLaunchError(gdbserial.LLDBLaunch(processArgs, wd, launchFlags, d.config.DebugInfoDirectories, d.config.TTY, [3]string{d.config.Stdin, d.config.Stdout.Path, d.config.Stderr.Path}))
		}
		return native.Launch(processArgs, wd, launchFlags, d.config.DebugInfoDirectories, d.config.TTY, d.config.Stdin, d.config.Stdout, d.config.Stderr)
	default:
		return nil, fmt.Errorf("unknown backend %q", d.config.Backend)
	}
}

func (d *Debugger) recordingStart(stop func() error) {
	d.recordMutex.Lock()
	d.stopRecording = stop
	d.recordMutex.Unlock()
}

func (d *Debugger) recordingDone() {
	d.recordMutex.Lock()
	d.stopRecording = nil
	d.recordMutex.Unlock()
}

func (d *Debugger) isRecording() bool {
	d.recordMutex.Lock()
	defer d.recordMutex.Unlock()

View on GitHub (pinned to a23773e6c3)

Solutions

Check the backend value passed in Config.Backend / the --backend flag; correct it to one of "default", "native", "lldb", or "rr".
Remove or unset the backend override so delve falls back to "default".
Run `dlv backend` help or check Documentation/usage to list valid backends for your platform.
If embedding delve via API, validate Config.Backend before calling debugger.New.

Example fix

// before
cfg.Backend = "Native"
// after
cfg.Backend = "native" // one of: default, native, lldb, rr

Defensive patterns

Strategy: validation

Validate before calling

var validBackends = map[string]bool{"default": true, "native": true, "lldb": true, "rr": true}
if !validBackends[cfg.Backend] {
    return fmt.Errorf("unsupported backend %q", cfg.Backend)
}
grp, err := debugger.New(&cfg, processArgs)

Prevention

Only pass backend values from a fixed allowlist, never raw user/env input.
Default to "default" (empty string) unless a specific backend is required.
Document platform-specific backends in your launcher config.

When it happens

Trigger: Calling debugger.New (which calls Launch) with Config.Backend set to a misspelled or unsupported value, e.g. "Native", "gdbserial", "core", or an empty string that survives defaulting. The default: branch in Launch is reached only for values outside the known set.

Common situations: Typo in --backend flag on the dlv command line; environment or config file exporting an invalid backend; tools embedding delve passing a backend name valid on another OS (e.g. "rr" on a system without rr, or macOS-only names); newer/older delve versions where a backend was renamed or removed.

Related errors

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