go-delve/delve · error

traverse failed with error %w

Error message

traverse failed with error %w

What it means

Returned by Debugger.Functions when a regex-matched function is walked with followCalls > 0 and the internal call-graph traversal (d.traverse) fails. The traverse walks a BFS over disassembled call instructions of the matched function and any error it encounters (disassembly failure, breakpoint setup failure, callback errors) is wrapped with this message. It means the follow-calls expansion of the function list could not be completed, so no usable function list is returned.

Source

Thrown at service/debugger/debugger.go:1399

// Functions returns a list of functions in the target process.
func (d *Debugger) Functions(filter string, followCalls int) ([]string, error) {
	d.targetMutex.Lock()
	defer d.targetMutex.Unlock()

	regex, err := regexp.Compile(filter)
	if err != nil {
		return nil, fmt.Errorf("invalid filter argument: %s", err.Error())
	}

	funcs := []string{}
	t := proc.ValidTargets{Group: d.target}
	for t.Next() {
		for _, f := range t.BinInfo().Functions {
			if regex.MatchString(f.Name) {
				if followCalls > 0 {
					newfuncs, err := d.traverse(t, &f, 1, followCalls, filter)
					if err != nil {
						return nil, fmt.Errorf("traverse failed with error %w", err)
					}
					funcs = append(funcs, newfuncs...)
				} else {
					funcs = append(funcs, f.Name)
				}
			}
		}
	}
	sort.Strings(funcs)
	funcs = slices.Compact(funcs)
	return funcs, nil
}

func (d *Debugger) traverse(t proc.ValidTargets, f *proc.Function, depth int, followCalls int, rootstr string) ([]string, error) {
	type TraceFunc struct {
		Func    *proc.Function
		Depth   int
		visited bool

View on GitHub (pinned to a23773e6c3)

Solutions

1. Read the wrapped inner error (%w) in the message to find the real failing step (disassemble, SetBreakpoint, stack trace, or registers).
2. Retry with followCalls=0 to confirm plain Functions(filter) works, isolating the failure to the traversal path.
3. Lower the followCalls depth so traversal stops before deep/runtime functions whose code cannot be disassembled.
4. Check the process is alive and the backend supports disassembly (e.g. core/gdbserial backends have restricted memory access).
5. Verify the binary is a supported architecture and not stripped/corrupt (go tool nm / dlv check).

Example fix

// before
funcs, err := client.Functions("main\.", 5)
// after
funcs, err := client.Functions("main\.", 0) // list only
if err == nil {
    funcs, err = client.Functions("main\.", 2) // smaller followCalls depth
}

// validate the filter regex compiles before the RPC call
if _, err := regexp.Compile(filter); err != nil {
    return fmt.Errorf("invalid filter: %w", err)
}
if followCalls < 0 {
    return fmt.Errorf("followCalls must be >= 0")
}

// errors.As to unwrap the underlying cause
var inner error
if errors.As(err, &inner) || strings.Contains(err.Error(), "traverse failed") {
    log.Printf("follow-calls traversal failed: %v", err)
}

funcs, err := client.Functions(filter, followCalls)
if err != nil && strings.Contains(err.Error(), "traverse failed") {
    log.Printf("follow-calls unavailable, falling back: %v", err)
    funcs, err = client.Functions(filter, 0)
}

When it happens

Trigger: Calling Debugger.Functions(filter, followCalls) with followCalls > 0 via RPC2 (or terminal `functions <filter> <followCalls>`) when: the target's memory cannot be disassembled (corrupt/unmapped code region, non-native backend without disassembly support), a temporary breakpoint cannot be set inside a dynamic-call site, or the runtime callback (stack trace / register read / tracepoint creation) fails during dynamic-call resolution.

Common situations: Debugging a core dump or stripped binary where Disassemble cannot decode a function's instructions; using follow-calls tracing on a Go binary built for an unsupported architecture; followCalls depth large enough that traversal reaches runtime stubs or dynamically linked regions; process exited or memory unreadable mid-traversal.

Related errors

• disassemble failed with error %w
• thread stack trace returned error
• failed to disassemble instruction: %w
• PCToFunc returned nil
• error calling traverse on dynamic children

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