go-delve/delve · error

not on topmost frame

Error message

not on topmost frame

What it means

Stepping commands like 'step' only operate on the topmost (innermost, frame 0) frame of the selected goroutine. errNotOnFrameZero is the sentinel error returned when the currently selected frame is not frame 0. This prevents stepping semantics that only make sense at the leaf of the call stack.

Source

Thrown at pkg/terminal/command.go:1480

func (c *Commands) step(t *Term, ctx callContext, args string) error {
	if err := scopePrefixSwitch(t, ctx); err != nil {
		return err
	}
	c.frame = 0
	stepfn := t.client.Step
	if ctx.Prefix == revPrefix {
		stepfn = t.client.ReverseStep
	}
	state, err := exitedToError(stepfn())
	if err != nil {
		printcontextNoState(t)
		return err
	}
	printcontext(t, state)
	return continueUntilCompleteNext(t, state, "step", true)
}

var errNotOnFrameZero = errors.New("not on topmost frame")

// stepInstruction implements the step-instruction (stepi) command.
func (c *Commands) stepInstruction(t *Term, ctx callContext, args string) error {
	return stepInstruction(t, ctx, c.frame, false)
}

// nextInstruction implements the next-instruction (nexti) command.
func (c *Commands) nextInstruction(t *Term, ctx callContext, args string) error {
	return stepInstruction(t, ctx, c.frame, true)
}

func stepInstruction(t *Term, ctx callContext, frame int, skipCalls bool) error {
	if err := scopePrefixSwitch(t, ctx); err != nil {
		return err
	}
	if frame != 0 {
		return errNotOnFrameZero
	}

View on GitHub (pinned to a23773e6c3)

Solutions

1. Switch back to the topmost frame with 'frame 0' or 'down'
2. Re-select the goroutine's current frame before stepping
3. Use 'stack' to confirm which frame is selected

Example fix

// before
(frame 2) step
// after
frame 0
step

// before stepping, ensure frame 0 is selected:
// run: frame 0   (or verify via 'stack')

if err := step(...); errors.Is(err, errNotOnFrameZero) || err.Error() == "not on topmost frame" { /* issue 'frame 0' then retry */ }

When it happens

Trigger: Selecting an older frame with 'frame 3' or 'up' and then running 'step', 'next', 'stepout', etc.: the command checks c.frame (or the selected frame index) and returns errNotOnFrameZero (pkg/terminal/command.go:1480).

Common situations: Inspecting a caller frame after a breakpoint and forgetting to switch back with 'frame 0' or 'down' before stepping; IDE-driven stepping while a non-zero frame is selected.

Related errors

• Invalid next count
• next while nexting
• command not available
• unknown config parameter
• not documented

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