What causes "builder rtinfo not found for builderid: %s" in wavetermdev/waveterm?

Confirm the builder exists (wstore list / UI) and use its current id

builder rtinfo not found for builderid: %s

Error message

builder rtinfo not found for builderid: %s

What it means

After validating BuilderId, StartBuilderCommand looks up the builder's runtime info via wstore.GetRTInfo on the ORef ("builder", builderId). If no RTInfo exists for that id, the server cannot determine which app to build or what env to use, and returns this error.

Source

Thrown at pkg/wshrpc/wshserver/wshserver.go:1144

	return waveappstore.WriteAppSecretBindings(data.AppId, data.Bindings)
}

func (ws *WshServer) DeleteBuilderCommand(ctx context.Context, builderId string) error {
	if builderId == "" {
		return fmt.Errorf("must provide a builderId to DeleteBuilderCommand")
	}
	buildercontroller.DeleteController(builderId)
	return nil
}

func (ws *WshServer) StartBuilderCommand(ctx context.Context, data wshrpc.CommandStartBuilderData) error {
	if data.BuilderId == "" {
		return fmt.Errorf("must provide a builderId to StartBuilderCommand")
	}
	bc := buildercontroller.GetOrCreateController(data.BuilderId)
	rtInfo := wstore.GetRTInfo(waveobj.MakeORef("builder", data.BuilderId))
	if rtInfo == nil {
		return fmt.Errorf("builder rtinfo not found for builderid: %s", data.BuilderId)
	}
	appId := rtInfo.BuilderAppId
	if appId == "" {
		return fmt.Errorf("builder appid not set for builderid: %s", data.BuilderId)
	}
	return bc.Start(ctx, appId, rtInfo.BuilderEnv)
}

func (ws *WshServer) StopBuilderCommand(ctx context.Context, builderId string) error {
	if builderId == "" {
		return fmt.Errorf("must provide a builderId to StopBuilderCommand")
	}
	bc := buildercontroller.GetController(builderId)
	if bc == nil {
		return nil
	}
	return bc.Stop()
}

View on GitHub (pinned to a4447c1563)

Solutions

Confirm the builder exists (wstore list / UI) and use its current id
Recreate the builder if its RTInfo record was lost
Refresh client-side builder state to purge stale ids

Example fix

// before
bc := buildercontroller.GetOrCreateController(staleId)
rtInfo := wstore.GetRTInfo(waveobj.MakeORef("builder", staleId)) // nil
// after
if wstore.GetRTInfo(waveobj.MakeORef("builder", builderId)) == nil {
    return fmt.Errorf("builder %q does not exist", builderId)
}

Defensive patterns

Strategy: validation

Validate before calling

rtInfo := wstore.GetRTInfo(waveobj.MakeORef("builder", builderId))
if rtInfo == nil {
    return fmt.Errorf("builder %q has no RTInfo; cannot start", builderId)
}
err := client.StartBuilderCommand(ctx, wshrpc.CommandStartBuilderData{BuilderId: builderId})

Type guard

func builderExists(builderId string) bool {
    return builderId != "" && wstore.GetRTInfo(waveobj.MakeORef("builder", builderId)) != nil
}

Try / catch

if err := client.StartBuilderCommand(ctx, data); err != nil {
    if strings.Contains(err.Error(), "rtinfo not found") {
        // refresh builder list, drop stale id, surface 'builder no longer exists'
    }
    return err
}

Prevention

Refresh cached builder ids after workspace/subscribe updates
Delete client-side references when a builder is removed
Use OIDs (from wstore), never names, as BuilderId

When it happens

Trigger: Calling StartBuilderCommand with a BuilderId that has no RTInfo entry in wstore — the builder object was deleted, the id is mistyped/stale, or RTInfo was never persisted for this builder.

Common situations: Using a cached builder id after the builder was removed; cross-workspace calls where the builder exists in a different workspace's store; a crash during builder creation that left the id without RTInfo.

Understand the failure class

Background: "Not found" and "does not exist" errors: why "Task not found", "No such folder", and "Can't find" fire when a lookup comes back empty — this error's family across 14 libraries.

Related errors

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