wavetermdev/waveterm · error

--border-color: %v

Error message

--border-color: %v

What it means

Wrapper around validateColor specifically for the --border-color flag: when the flag was explicitly provided, its value is validated and any failure is re-raised prefixed with "--border-color: ". The root cause is always one of the color validation errors (missing '#', wrong hex length, bad hex digits, unknown color name).

Source

Thrown at cmd/wsh/cmd/wshcmd-setbg.go:101

		return validateHexColor(color)
	}
	if !CssColorNames[strings.ToLower(color)] {
		return fmt.Errorf("invalid color %q: must be a hex color (#RRGGBB or #RRGGBBAA) or a CSS color name", color)
	}
	return nil
}

func setBgRun(cmd *cobra.Command, args []string) (rtnErr error) {
	defer func() {
		sendActivity("setbg", rtnErr == nil)
	}()

	borderColorChanged := cmd.Flags().Changed("border-color")
	activeBorderColorChanged := cmd.Flags().Changed("active-border-color")

	if borderColorChanged {
		if err := validateColor(setBgBorderColor); err != nil {
			return fmt.Errorf("--border-color: %v", err)
		}
	}
	if activeBorderColorChanged {
		if err := validateColor(setBgActiveBorderColor); err != nil {
			return fmt.Errorf("--active-border-color: %v", err)
		}
	}

	// Create base metadata
	meta := map[string]interface{}{}

	// Handle opacity-only change or clear
	if len(args) == 0 {
		if !cmd.Flags().Changed("opacity") && !setBgClear && !borderColorChanged && !activeBorderColorChanged {
			OutputHelpMessage(cmd)
			return fmt.Errorf("setbg requires an image path or color value")
		}
		if setBgOpacity < 0 || setBgOpacity > 1 {

View on GitHub (pinned to a4447c1563)

Solutions

1. Quote the value and include '#': `wsh setbg --border-color '#00FF00'`.
2. Use a valid CSS color name: `--border-color green`.
3. Check the wrapped message after the prefix to see which validation rule failed (format vs digits vs name).

Example fix

// before
wsh setbg --border-color 00FF00
// after
wsh setbg --border-color '#00FF00'

if bc := flags["--border-color"]; bc != "" && !isAcceptableColor(bc) {
    return fmt.Errorf("--border-color %q invalid: use '#RRGGBB', '#RRGGBBAA', or a CSS name", bc)
}

func isAcceptableColor(c string) bool {
    if strings.HasPrefix(c, "#") { return regexp.MustCompile(`^#[0-9a-fA-F]{6}([0-9a-fA-F]{2})?$`).MatchString(c) }
    return CssColorNames[strings.ToLower(c)]
}

if err := run(); err != nil {
    var ve *colorFlagError
    if errors.As(err, &ve) && ve.Flag == "--border-color" { /* fix the border-color value and retry */ }
}

When it happens

Trigger: Any `wsh setbg --border-color <invalid>` invocation where the value is not '#' hex in 6/8-digit form nor a CSS color name.

Common situations: Shell eating the '#' (unquoted '#FF0000' becomes empty/commented in some shells); typos; 3-digit hex shorthand.

Related errors

• --active-border-color: %v
• --workspace and --window are mutually exclusive; specify onl
• color must start with #
• color must be in #RRGGBB or #RRGGBBAA format
• invalid hex color: %v

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