go-delve/delve · error

unknown API version

Error message

unknown API version

What it means

rpccommon.Server.Run validates config.APIVersion and only serves version 2 (a default of 2 is applied when it is 0). Any other configured version causes startup to fail with 'unknown API version'.

Source

Thrown at service/rpccommon/server.go:114

	}
	if s.debugger.IsRunning() {
		s.debugger.Command(&api.DebuggerCommand{Name: api.Halt}, nil, nil, nil)
	}
	kill := s.config.Debugger.AttachPid == 0
	return s.debugger.Detach(kill)
}

// Run starts a debugger and exposes it with an JSON-RPC server. The debugger
// itself can be stopped with the `detach` API.
func (s *ServerImpl) Run() error {
	var err error

	if s.config.APIVersion == 0 {
		s.config.APIVersion = 2
	}

	if s.config.APIVersion != 2 {
		return errors.New("unknown API version")
	}

	// Create and start the debugger
	config := s.config.Debugger
	if s.debugger, err = debugger.New(&config, s.config.ProcessArgs); err != nil {
		return err
	}

	s.s2 = rpc2.NewServer(s.config, s.debugger)

	rpcServer := &RPCServer{s}

	s.methodMaps = make([]map[string]*methodType, 2)

	s.methodMaps[1] = map[string]*methodType{}

	suitableMethods2(s.s2, s.methodMaps[1])
	suitableMethodsCommon(rpcServer, s.methodMaps[1])

View on GitHub (pinned to a23773e6c3)

Solutions

1. Set config.APIVersion = 2 (or leave it 0 to get the default).
2. Remove stale APIVersion settings from embedded configs.
3. If version 1 behavior is needed, use a Delve release that still supports it.

Example fix

// before
cfg := &service.Config{APIVersion: 1}
// after
cfg := &service.Config{APIVersion: 2}

if cfg.APIVersion != 0 && cfg.APIVersion != 2 {
    cfg.APIVersion = 2
}

if err := srv.Run(); err != nil {
    if strings.Contains(err.Error(), "unknown API version") {
        // fix config and restart server
    }
}

When it happens

Trigger: Creating/starting a rpccommon.Server with config.APIVersion set to anything other than 0 or 2 (e.g. 1 or 3).

Common situations: Embedding Delve in another tool with an older config that used APIVersion 1, or guessing a newer version number.

Related errors

• can not call function with nil ReturnInfoLoadConfig
• cannot restart process Delve did not create
• channel filter can not be negated
• count == 0 not allowed with a channel filter
• channel filter without eval scope

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