wavetermdev/waveterm · error

oref is required

Error message

oref is required

What it means

Returned when the request requires an oref (object reference) but none was supplied.

Source

Thrown at pkg/wshrpc/wshremote/wshremote.go:146

}

func (impl *ServerImpl) getWshPath() (string, error) {
	if impl.IsLocal {
		return filepath.Join(wavebase.GetWaveDataDir(), "bin", "wsh"), nil
	}
	wshPath, err := wavebase.ExpandHomeDir("~/.waveterm/bin/wsh")
	if err != nil {
		return "", fmt.Errorf("cannot expand wsh path: %w", err)
	}
	return wshPath, nil
}

func (impl *ServerImpl) BadgeWatchPidCommand(ctx context.Context, data wshrpc.CommandBadgeWatchPidData) error {
	if data.Pid <= 0 {
		return fmt.Errorf("invalid pid: %d", data.Pid)
	}
	if data.ORef.IsEmpty() {
		return fmt.Errorf("oref is required")
	}
	if data.BadgeId == "" {
		return fmt.Errorf("badgeid is required")
	}
	go func() {
		defer func() {
			panichandler.PanicHandler("BadgeWatchPidCommand", recover())
		}()
		for {
			time.Sleep(time.Second)
			if unixutil.IsPidRunning(data.Pid) {
				continue
			}
			orefStr := data.ORef.String()
			event := wps.WaveEvent{
				Event:  wps.Event_Badge,
				Scopes: []string{orefStr},
				Data: baseds.BadgeEvent{

View on GitHub (pinned to a4447c1563)

Solutions

1. Populate ORef from the current block/conn context before calling
2. Validate !oRef.IsEmpty() in the sender
3. Ensure serialization includes the oref field

if data.ORef.IsEmpty() {
    return fmt.Errorf("oref must be set from block context before watching badge")
}

if err := BadgeWatchPidCommand(ctx, data); err != nil {
    if strings.Contains(err.Error(), "oref is required") {
        return fmt.Errorf("caller bug: badge watch missing oref")
    }
    return err
}

When it happens

Trigger: Calling BadgeWatchPidCommand with CommandBadgeWatchPidData.ORef left as zero value (empty oref).

Common situations: Constructing the command data struct and forgetting to set ORef from the block context; deserializing partial JSON payloads.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• invalid object reference: %q
• error parsing object reference: %w
• invalid oref string: %v
• invalid pid: %d
• badgeid is required

AI-assisted analysis of wavetermdev/waveterm@a4447c1563 (2026-09-01). Data as JSON: /api/errors/1e89e8d097e98b3d. Report an issue: GitHub.