go-delve/delve · error

unknown debug event code: %d

Error message

unknown debug event code: %d

What it means

In the Windows native backend's debug event loop, waitForDebugEvent receives DEBUG_EVENT structures with a DebugEventCode. The switch handles the known codes (create/load/exit events); if the OS delivers a code the backend does not recognize, it returns this error instead of continuing. This usually means the backend needs updating for an event type it doesn't yet handle, or that event code state was corrupted.

Source

Thrown at pkg/proc/native/proc_windows.go:508

				// This exception is sent to set the thread name in VisualC, we should
				// mask it or it might crash the program.
				continueStatus = _DBG_CONTINUE
			default:
				continueStatus = _DBG_EXCEPTION_NOT_HANDLED
			}
		case _EXIT_PROCESS_DEBUG_EVENT:
			debugInfo := (*_EXIT_PROCESS_DEBUG_INFO)(unionPtr)
			dbp := procgrp.procForPid(int(debugEvent.ProcessId))
			dbp.postExit()
			if procgrp.numValid() == 0 {
				err = _ContinueDebugEvent(debugEvent.ProcessId, debugEvent.ThreadId, continueStatus)
				if err != nil {
					return 0, err
				}
				return 0, proc.ErrProcessExited{Pid: dbp.pid, Status: int(debugInfo.ExitCode)}
			}
		default:
			return 0, fmt.Errorf("unknown debug event code: %d", debugEvent.DebugEventCode)
		}

		// .. and then continue unless we received an event that indicated we should break into debugger.
		err = _ContinueDebugEvent(debugEvent.ProcessId, debugEvent.ThreadId, continueStatus)
		if err != nil {
			return 0, err
		}
	}
}

func trapWait(procgrp *processGroup, pid int) (*nativeThread, error) {
	var err error
	var tid int
	procgrp.procs[0].execPtraceFunc(func() {
		tid, err = procgrp.waitForDebugEvent(waitBlocking)
	})
	if err != nil {
		return nil, err

View on GitHub (pinned to a23773e6c3)

Solutions

1. Record the DebugEventCode value from the error message and report it to the Delve project with the Windows version.
2. Update Delve to the latest version — new Windows event codes are sometimes added.
3. Check the Windows SDK documentation for the code (bit 31-30 severity, 29 customer bit) to identify the event type.
4. As a workaround, retry the operation; a single unrecognized event may not be fatal to the debug session.

Example fix

// before
dlv exec app.exe
// unknown debug event code: 2147549185
// after
# upgrade delve to pick up new event-code handling
go install github.com/go-delve/delve/cmd/dlv@latest
dlv exec app.exe

_, err := dbg.Command(&api.DebuggerCommand{Name: "continue"})
if err != nil {
    var unk *fmt.Errorf // match by message
    if strings.Contains(err.Error(), "unknown debug event code") {
        // extract the code, check Windows SDK docs, upgrade delve, report issue
    }
}

When it happens

Trigger: Calling continue/step operations on Windows when WaitForDebugEvent returns a DebugEventCode outside the handled set (exception, create process/thread, exit process/thread, DLL load/unload, rip event, etc.).

Common situations: Attaching to processes that generate unusual debug events (e.g. adjunct/ETW-triggered events on unusual Windows builds); custom or preview Windows versions producing new event codes; extremely rare corruption.

Related errors

• lldb backend not supported on Windows
• NtQueryInformationThread failed: it returns 0x%x
• backend does not support function calls
• VirtualQueryEx wrapped around the address space or stuck
• process must be stopped in order to kill it

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