What causes "error parsing command map: %w" in wavetermdev/waveterm?

Read the wrapped cause to see which field failed validation.

error parsing command map: %w

Error message

error parsing command map: %w

What it means

convertWSCommand found a map-shaped argument, but webcmd.ParseWSCommandMap rejected its contents - the map does not parse into a valid WSCommand. The %w-wrapped cause explains what was missing or invalid.

Source

Thrown at pkg/service/service.go:108

	nativeArgVal := reflect.New(argType)
	err := utilfn.DoMapStructure(nativeArgVal.Interface(), jsonArg)
	if err != nil {
		return nil, err
	}
	return nativeArgVal.Elem().Interface(), nil
}

func isSpecialWaveArgType(argType reflect.Type) bool {
	return argType == waveObjRType || argType == waveObjSliceRType || argType == waveObjMapRType || argType == wsCommandRType
}

func convertWSCommand(argType reflect.Type, jsonArg any) (any, error) {
	if _, ok := jsonArg.(map[string]any); !ok {
		return nil, fmt.Errorf("cannot convert %T to %s", jsonArg, argType)
	}
	cmd, err := webcmd.ParseWSCommandMap(jsonArg.(map[string]any))
	if err != nil {
		return nil, fmt.Errorf("error parsing command map: %w", err)
	}
	return cmd, nil
}

func convertSpecial(argType reflect.Type, jsonArg any) (any, error) {
	jsonType := reflect.TypeOf(jsonArg)
	if argType == orefRType {
		if jsonType.Kind() != reflect.String {
			return nil, fmt.Errorf("cannot convert %T to %s", jsonArg, argType)
		}
		oref, err := waveobj.ParseORef(jsonArg.(string))
		if err != nil {
			return nil, fmt.Errorf("invalid oref string: %v", err)
		}
		return oref, nil
	} else if argType == wsCommandRType {
		return convertWSCommand(argType, jsonArg)
	} else if argType == waveObjRType {

View on GitHub (pinned to a4447c1563)

Solutions

Read the wrapped cause to see which field failed validation.
Ensure the map includes the required fields ParseWSCommandMap expects (typically a non-empty 'command' string).
Construct the command via the SDK's WSCommand type and serialize it instead of hand-building the map.

Example fix

// before
map[string]any{"cmd": "run", "args": []any{"ls"}}
// after
map[string]any{"command": "run", "args": []any{"ls"}}

Defensive patterns

Strategy: validation

Validate before calling

cmdMap, _ := arg.(map[string]any)
if name, _ := cmdMap["command"].(string); name == "" {
    return fmt.Errorf("WSCommand requires a non-empty 'command' field")
}

Try / catch

cmd, err := webcmd.ParseWSCommandMap(m)
if err != nil {
    return fmt.Errorf("invalid command payload: %w", err)
}

Prevention

Use typed WSCommand constructors instead of raw maps.
Validate 'command' and required fields on the client before sending.
Version-check protocol shapes between frontend and backend.

When it happens

Trigger: The JSON map passed for a WSCommand parameter lacks the required 'command' field, has wrong-typed fields, or otherwise violates ParseWSCommandMap's expected structure.

Common situations: Hand-rolled RPC calls with misspelled keys ('cmd' instead of 'command'); partial command objects after JSON round-trips dropped fields; version mismatch on expected fields.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

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