What causes "setbg requires an image path or color value" in wavetermdev/waveterm?

Pass an argument: `wsh setbg /path/to/image.png` or `wsh setbg '#1a1a2e'`.

setbg requires an image path or color value

Error message

setbg requires an image path or color value

What it means

`wsh setbg` with no positional argument only makes sense when at least one modifier flag (--opacity, --clear, --border-color, --active-border-color) is given; otherwise there is nothing to do. If no args and no relevant flags were changed, the CLI prints help and returns this error instead of silently no-oping.

Source

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

	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 {
			return fmt.Errorf("opacity must be between 0.0 and 1.0")
		}
		if setBgClear {
			meta["bg:*"] = true
		} else if cmd.Flags().Changed("opacity") {
			meta["bg:opacity"] = setBgOpacity
		}
	} else if len(args) > 1 {
		OutputHelpMessage(cmd)
		return fmt.Errorf("too many arguments")
	} else {
		// Handle background setting
		meta["bg:*"] = true
		meta["tab:background"] = nil
		if setBgOpacity < 0 || setBgOpacity > 1 {
			return fmt.Errorf("opacity must be between 0.0 and 1.0")

View on GitHub (pinned to a4447c1563)

Solutions

Pass an argument: `wsh setbg /path/to/image.png` or `wsh setbg '#1a1a2e'`.
If you meant an opacity-only change, include --opacity: `wsh setbg --opacity 0.5`.
To clear the background, run `wsh setbg --clear`.
Check flag spelling (typos don't register as changed) and that shell variables are not empty.

Example fix

// before
BG="" ; wsh setbg "$BG"          # empty -> error
// after
wsh setbg --opacity 0.5           # or pass a real path/color argument

Defensive patterns

Strategy: validation

Validate before calling

if len(args) == 0 && opacityFlag == nil && !clearFlag && borderColor == "" && activeBorderColor == "" {
    return errors.New("setbg needs an image path or color, or a modifier flag like --opacity/--clear")
}

Try / catch

if err := run(); err != nil {
    if strings.Contains(err.Error(), "requires an image path or color value") { /* print usage or apply a default */ }
}

Prevention

Always pass a positional image path or color unless using --opacity-only or --clear.
Double-check flag spelling — typos don't count as 'changed' flags.
Guard shell variables: use "${BG:?unset}" so empty values fail early.

When it happens

Trigger: Running `wsh setbg` bare, or with only flags not counted here (e.g. a typo'd flag name so Flags().Changed sees nothing), and no positional image path/color argument.

Common situations: Forgetting the image path; a misspelled flag (--opaciy) that silently isn't 'changed', leaving args empty; piping an empty variable: `wsh setbg "$BG"` with BG unset.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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