wavetermdev/waveterm · error

invalid mode %q (expected %q or %q)

Error message

invalid mode %q (expected %q or %q)

What it means

wsh debugterm validates the --mode flag by lowercasing it and comparing against the two allowed modes (hex and decode). If any other value is supplied, getDebugTermMode returns this error and the debugterm command aborts before setting up the RPC client connection.

Source

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

		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)
}

func getDebugTermMode() (string, error) {
	mode := strings.ToLower(debugTermMode)
	if mode != DebugTermModeHex && mode != DebugTermModeDecode {
		return "", fmt.Errorf("invalid mode %q (expected %q or %q)", debugTermMode, DebugTermModeHex, DebugTermModeDecode)
	}
	return mode, nil
}

type debugTermStdinEntry struct {
	Data string `json:"data"`
}

func parseDebugTermStdinData(data []byte) ([]byte, error) {
	trimmed := strings.TrimSpace(string(data))
	if len(trimmed) == 0 {
		return data, nil
	}
	if trimmed[0] == '[' {
		// try array of structs first
		var structArr []debugTermStdinEntry
		err := json.Unmarshal(data, &structArr)
		if err == nil {

View on GitHub (pinned to a4447c1563)

Solutions

1. Run `wsh debugterm --help` to see allowed modes
2. Pass exactly `hex` or `decode` (case-insensitive) to --mode
3. Fix the value in your script/alias that supplies the mode

Example fix

// before
wsh debugterm --mode hexdump
// after
wsh debugterm --mode hex

mode := strings.ToLower(os.Args[len(os.Args)-1]) // value you plan to pass
if mode != "hex" && mode != "decode" {
    return fmt.Errorf("unsupported debugterm mode %q; use hex or decode", mode)
}

func isValidDebugTermMode(s string) bool {
    switch strings.ToLower(s) {
    case "hex", "decode":
        return true
    }
    return false
}

When it happens

Trigger: Running `wsh debugterm --mode <anything-other-than-hex-or-decode>`, including misspellings like 'hexdump', 'Hex ' with whitespace, or 'raw'.

Common situations: Guessing at mode names instead of checking `wsh debugterm --help`; scripting the command with a variable that holds an unsupported mode; copy-pasting flags from other wsh subcommands.

Understand the failure class

Background: "unknown output mode", "invalid value for flag", "expects true/false": fixing invalid flag value errors in CLI tools — this error's family across 24 libraries.

Related errors

• no arguments. wsh editor requires a file or URL as an argum
• too many arguments. wsh editor requires exactly one argumen
• badge oref must be a block or tab (got %q)
• unknown --view %q; try one of: term, web, preview, edit, sys
• --workspace and --window are mutually exclusive; specify onl

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