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.

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

• badgeid is required
• error parsing object reference
• invalid object reference
• invalid oref string
• invalid pid

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

Appendix: 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)