What causes "oscNum must be 5 characters" in wavetermdev/waveterm?

Pass a 5-character OSC number including the trailing semicolon, e.g. "1337;".

oscNum must be 5 characters

Error message

oscNum must be 5 characters

What it means

EncodeWaveOSCBytes requires the OSC escape number (oscNum) to be exactly 5 characters, matching the internal Wave OSC prefix format. Passing any other length string is rejected up front because it would produce a malformed escape sequence the terminal parser cannot recognize.

Source

Thrown at pkg/wshutil/wshutil.go:76

	dst[0] = ESC
	dst[1] = ']'
	copy(dst[2:], oscNum)
	dst[len(oscNum)+2] = ';'
}

func oscPrefixLen(oscNum string) int {
	return 3 + len(oscNum)
}

func makeOscPrefix(oscNum string) []byte {
	output := make([]byte, oscPrefixLen(oscNum))
	copyOscPrefix(output, oscNum)
	return output
}

func EncodeWaveOSCBytes(oscNum string, barr []byte) ([]byte, error) {
	if len(oscNum) != 5 {
		return nil, fmt.Errorf("oscNum must be 5 characters")
	}
	const maxSize = 64 * 1024 * 1024 // 64 MB
	if len(barr) > maxSize {
		return nil, fmt.Errorf("input data too large")
	}
	hasControlChars := false
	for _, b := range barr {
		if b < 0x20 || b == 0x7F {
			hasControlChars = true
			break
		}
	}
	if !hasControlChars {
		// If no control characters, directly construct the output
		// \x1b] (2) + WaveOSC + ; (1) + message + \x07 (1)
		output := make([]byte, oscPrefixLen(oscNum)+len(barr)+1)
		copyOscPrefix(output, oscNum)
		copy(output[oscPrefixLen(oscNum):], barr)

View on GitHub (pinned to a4447c1563)

Solutions

Pass a 5-character OSC number including the trailing semicolon, e.g. "1337;".
Verify the constant used matches the one Wave's decoder (DecodeWaveOSCBytes) expects.
Add a startup-time assertion if the oscNum is constructed dynamically.

Example fix

// before
EncodeWaveOSCBytes("1337", barr)
// after
EncodeWaveOSCBytes("1337;", barr) // must be exactly 5 chars

Defensive patterns

Strategy: validation

Validate before calling

if len(oscNum) != 5 {
    return errors.New("oscNum must be exactly 5 characters, e.g. \"1337;\"")
}

Type guard

func isValidOscNum(s string) bool { return len(s) == 5 }

Try / catch

if !isValidOscNum(oscNum) {
    return fmt.Errorf("bad oscNum %q", oscNum)
}
barr, err := EncodeWaveOSCBytes(oscNum, barr)
if err != nil { return err }

Prevention

Use a named constant for the OSC number instead of string literals
Always include the trailing semicolon in the Wave OSC number
Write a unit test asserting the constant length

When it happens

Trigger: Calling EncodeWaveOSCBytes, AdaptMsgChToPty, or EncodeWaveOSCMessageEx with an oscNum/oscEsc argument whose len != 5, e.g. "2000" or "1337" (4 chars) instead of "1337;".

Common situations: Typos in the OSC escape constant; removing the trailing semicolon; hardcoding a 4-digit OSC number from other terminal conventions (e.g. iTerm2's 1337).

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

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