What causes "must provide an appId to RenameAppFileCommand" in wavetermdev/waveterm?

Populate CommandRenameAppFileData.AppId with the wave app's OID before invoking the RPC

must provide an appId to RenameAppFileCommand

Error message

must provide an appId to RenameAppFileCommand

What it means

Wave Terminal's WSH RPC server validates that a RenameAppFileCommand request carries a non-empty AppId before delegating to waveappstore.RenameAppFile. The appId identifies which app's file store the rename targets; without it the operation would be ambiguous. The server rejects the call immediately with this error.

Source

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

	err = waveappstore.WriteAppFile(data.AppId, "app.go", formattedOutput)
	if err != nil {
		return nil, err
	}

	encoded := base64.StdEncoding.EncodeToString(formattedOutput)
	return &wshrpc.CommandWriteAppGoFileRtnData{Data64: encoded}, nil
}

func (ws *WshServer) DeleteAppFileCommand(ctx context.Context, data wshrpc.CommandDeleteAppFileData) error {
	if data.AppId == "" {
		return fmt.Errorf("must provide an appId to DeleteAppFileCommand")
	}
	return waveappstore.DeleteAppFile(data.AppId, data.FileName)
}

func (ws *WshServer) RenameAppFileCommand(ctx context.Context, data wshrpc.CommandRenameAppFileData) error {
	if data.AppId == "" {
		return fmt.Errorf("must provide an appId to RenameAppFileCommand")
	}
	return waveappstore.RenameAppFile(data.AppId, data.FromFileName, data.ToFileName)
}

func (ws *WshServer) WriteAppSecretBindingsCommand(ctx context.Context, data wshrpc.CommandWriteAppSecretBindingsData) error {
	if data.AppId == "" {
		return fmt.Errorf("must provide an appId to WriteAppSecretBindingsCommand")
	}
	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
}

View on GitHub (pinned to a4447c1563)

Solutions

Populate CommandRenameAppFileData.AppId with the wave app's OID before invoking the RPC
Verify the caller's source of the appId (e.g. block controller or RTInfo lookup) actually returns a value
Log/inspect the outgoing RPC data payload to confirm AppId is serialized non-empty

Example fix

// before
data := wshrpc.CommandRenameAppFileData{FromFileName: "a.json", ToFileName: "b.json"}
// after
data := wshrpc.CommandRenameAppFileData{AppId: appId, FromFileName: "a.json", ToFileName: "b.json"}

Defensive patterns

Strategy: validation

Validate before calling

if data.AppId == "" {
    return fmt.Errorf("cannot rename app file: AppId is empty")
}
err := client.RenameAppFileCommand(ctx, data)

Type guard

func hasAppId(data wshrpc.CommandRenameAppFileData) bool {
    return data.AppId != ""
}

Try / catch

if err := client.RenameAppFileCommand(ctx, data); err != nil {
    if strings.Contains(err.Error(), "must provide an appId") {
        // fix: resolve and set data.AppId, then retry once
    }
    return err
}

Prevention

Always construct RPC data structs via helpers that fill AppId from the block/app context
Assert AppId non-empty in client code before every app-store RPC
Log the full RPC payload on failure for easier diagnosis

When it happens

Trigger: Calling RenameAppFileCommand via wsh RPC with CommandRenameAppFileData where the AppId field is the empty string — e.g. the client built the data struct without filling AppId, or an upstream lookup that was supposed to supply the appId returned empty.

Common situations: Frontend code resolving an app from a block/tab context that has no associated app; stale or corrupted client state where the appId was lost; a caller constructing the command data by hand for scripting/testing and omitting the field.

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

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