What causes "decoding terminal output: %w" in wavetermdev/waveterm?

Update wsh and Wave Terminal to matching versions

decoding terminal output: %w

Error message

decoding terminal output: %w

What it means

After a successful DebugTermCommand, the response's Data64 field is base64-decoded; a decode failure is wrapped as 'decoding terminal output'. This indicates the server returned a malformed base64 payload — a protocol/data corruption issue rather than a user input problem.

Source

Thrown at cmd/wsh/cmd/wshcmd-debugterm.go:107

		return nil
	}
	if debugTermSize <= 0 {
		return fmt.Errorf("size must be greater than 0")
	}
	fullORef, err := resolveBlockArg()
	if err != nil {
		return err
	}
	rtn, err := wshclient.DebugTermCommand(RpcClient, wshrpc.CommandDebugTermData{
		BlockId: fullORef.OID,
		Size:    debugTermSize,
	}, &wshrpc.RpcOpts{Timeout: 2000})
	if err != nil {
		return fmt.Errorf("reading terminal output: %w", err)
	}
	termData, err := base64.StdEncoding.DecodeString(rtn.Data64)
	if err != nil {
		return fmt.Errorf("decoding terminal output: %w", err)
	}
	var output string
	if mode == DebugTermModeDecode {
		output = formatDebugTermDecode(termData)
	} else {
		output = formatDebugTermHex(termData)
	}
	WriteStdout("%s", output)
	return nil
}

func debugTermPreRun(cmd *cobra.Command, args []string) error {
	if debugTermStdin || debugTermInput != "" {
		return nil
	}
	return preRunSetupRpcClient(cmd, args)
}

View on GitHub (pinned to a4447c1563)

Solutions

Update wsh and Wave Terminal to matching versions
Re-run the command to rule out a one-off corrupted response
Inspect the raw rtn payload (server logs) to see what Data64 actually contained
Report/patch upstream if the server handler emits non-base64 Data64

Example fix

// before
old-wsh debugterm <blockid> --size 4096   # version mismatch corrupts payload
// after
# upgrade both sides, then:
wsh debugterm <blockid> --size 4096

Defensive patterns

Strategy: type-guard

Validate before calling

// sanity-check the payload shape before decoding:
if rtn == nil || rtn.Data64 == "" || len(rtn.Data64)%4 != 0 || !isBase64(rtn.Data64) {
	return fmt.Errorf("malformed Data64 payload from server")
}

func isBase64(s string) bool {
	_, err := base64.StdEncoding.DecodeString(s)
	return err == nil
}

Type guard

func isValidBase64(s string) bool {
	if s == "" || len(s)%4 != 0 {
		return false
	}
	_, err := base64.StdEncoding.DecodeString(s)
	return err == nil
}

Try / catch

termData, err := base64.StdEncoding.DecodeString(rtn.Data64)
if err != nil {
	return fmt.Errorf("decoding terminal output: %w (payload len=%d; check wsh/Wave version match)", err, len(rtn.Data64))
}

Prevention

Keep wsh CLI and Wave Terminal on the same version
Log the payload length and a prefix when decoding fails to spot corruption
Re-run once to rule out a transient corrupted response
Never modify the RPC response in transit (avoid re-wrapping through proxies/scripts)

When it happens

Trigger: The RPC succeeds but rtn.Data64 contains invalid base64 (corrupted response, version mismatch between wsh client and Wave server RPC handlers, or an error string placed in Data64).

Common situations: Mismatched wsh and Wave Terminal versions where the RPC payload format changed; a proxy or wrapper corrupting the response; backend bug returning non-base64 data in Data64.

Related errors

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