{"record":{"id":"7ff2215a2b2f2201","repo":"wavetermdev/waveterm","slug":"opacity-must-be-between-0-0-and-1-0","errorCode":null,"errorMessage":"opacity must be between 0.0 and 1.0","messagePattern":"opacity must be between 0\\.0 and 1\\.0","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/wsh/cmd/wshcmd-setbg.go","lineNumber":120,"sourceCode":"\t\t}\n\t}\n\tif activeBorderColorChanged {\n\t\tif err := validateColor(setBgActiveBorderColor); err != nil {\n\t\t\treturn fmt.Errorf(\"--active-border-color: %v\", err)\n\t\t}\n\t}\n\n\t// Create base metadata\n\tmeta := map[string]interface{}{}\n\n\t// Handle opacity-only change or clear\n\tif len(args) == 0 {\n\t\tif !cmd.Flags().Changed(\"opacity\") && !setBgClear && !borderColorChanged && !activeBorderColorChanged {\n\t\t\tOutputHelpMessage(cmd)\n\t\t\treturn fmt.Errorf(\"setbg requires an image path or color value\")\n\t\t}\n\t\tif setBgOpacity < 0 || setBgOpacity > 1 {\n\t\t\treturn fmt.Errorf(\"opacity must be between 0.0 and 1.0\")\n\t\t}\n\t\tif setBgClear {\n\t\t\tmeta[\"bg:*\"] = true\n\t\t} else if cmd.Flags().Changed(\"opacity\") {\n\t\t\tmeta[\"bg:opacity\"] = setBgOpacity\n\t\t}\n\t} else if len(args) > 1 {\n\t\tOutputHelpMessage(cmd)\n\t\treturn fmt.Errorf(\"too many arguments\")\n\t} else {\n\t\t// Handle background setting\n\t\tmeta[\"bg:*\"] = true\n\t\tmeta[\"tab:background\"] = nil\n\t\tif setBgOpacity < 0 || setBgOpacity > 1 {\n\t\t\treturn fmt.Errorf(\"opacity must be between 0.0 and 1.0\")\n\t\t}\n\t\tmeta[\"bg:opacity\"] = setBgOpacity\n","sourceCodeStart":102,"sourceCodeEnd":138,"githubUrl":"https://github.com/wavetermdev/waveterm/blob/a4447c1563b2df285ab89e76c82f91e1a1a49c1e/cmd/wsh/cmd/wshcmd-setbg.go#L102-L138","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Re-run with a decimal value between 0.0 and 1.0, e.g. `wsh setbg --opacity 0.8`","If your value is a percentage, divide by 100 first (80 -> 0.8)","Remember opacity defaults to 0.5; omit the flag if 0.5 is acceptable"],"exampleFix":"// before\nwsh setbg --opacity 80\n// after\nwsh setbg --opacity 0.8","handlingStrategy":"validation","validationCode":"const opacity = 0.8;\nif (typeof opacity !== \"number\" || Number.isNaN(opacity) || opacity < 0 || opacity > 1) {\n  throw new RangeError(`opacity must be between 0.0 and 1.0, got ${opacity}`);\n}\n// then: wsh setbg --opacity ${opacity}","typeGuard":"function isValidOpacity(v) {\n  return typeof v === \"number\" && Number.isFinite(v) && v >= 0 && v <= 1;\n}","tryCatchPattern":null,"preventionTips":["Always express opacity as a 0-1 decimal, never a percentage","Clamp computed opacities: Math.min(Math.max(v, 0), 1)","Dry-run with --print to inspect the metadata before applying"],"tags":["cli","validation","waveterm"],"backgroundTag":"parameter-out-of-range","analyzedSha":"a4447c1563b2df285ab89e76c82f91e1a1a49c1e","analyzedAt":"2026-09-01T15:26:23.972Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}