wavetermdev/waveterm · error

opacity must be between 0.0 and 1.0

Error message

opacity must be between 0.0 and 1.0

What it means

The `wsh setbg` command validates that the --opacity flag value lies in [0.0, 1.0]. Because --opacity has a default of 0.5, the flag itself always parses; this error fires when the user explicitly passes a value outside the allowed range (negative or greater than 1) in the no-argument branch (opacity-only/clear/border-color change). It is a client-side input validation error, thrown before any RPC is sent.

Source

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

		}
	}
	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")
		}
		meta["bg:opacity"] = setBgOpacity

View on GitHub (pinned to a4447c1563)

Solutions

1. Re-run with a decimal value between 0.0 and 1.0, e.g. `wsh setbg --opacity 0.8`
2. If your value is a percentage, divide by 100 first (80 -> 0.8)
3. Remember opacity defaults to 0.5; omit the flag if 0.5 is acceptable

Example fix

// before
wsh setbg --opacity 80
// after
wsh setbg --opacity 0.8

const opacity = 0.8;
if (typeof opacity !== "number" || Number.isNaN(opacity) || opacity < 0 || opacity > 1) {
  throw new RangeError(`opacity must be between 0.0 and 1.0, got ${opacity}`);
}
// then: wsh setbg --opacity ${opacity}

function isValidOpacity(v) {
  return typeof v === "number" && Number.isFinite(v) && v >= 0 && v <= 1;
}

When it happens

Trigger: Running `wsh setbg --opacity 1.5`, `wsh setbg --opacity -0.2` (alone or with --clear/--border-color/--active-border-color but no image/color positional argument).

Common situations: Users pass opacity on a 0-100 scale (e.g. `--opacity 80`), or copy percentage strings like `--opacity 50%` from documentation; shell scripts computing opacity from fractions can also produce negative or >1 floats.

Related errors

• 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
• cannot parse connection name: %w
• --conn parameter is required

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