{"record":{"id":"23697d893e795da0","repo":"wavetermdev/waveterm","slug":"setbg-requires-an-image-path-or-color-value","errorCode":null,"errorMessage":"setbg requires an image path or color value","messagePattern":"setbg requires an image path or color value","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/wsh/cmd/wshcmd-setbg.go","lineNumber":117,"sourceCode":"\tif borderColorChanged {\n\t\tif err := validateColor(setBgBorderColor); err != nil {\n\t\t\treturn fmt.Errorf(\"--border-color: %v\", err)\n\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\")","sourceCodeStart":99,"sourceCodeEnd":135,"githubUrl":"https://github.com/wavetermdev/waveterm/blob/a4447c1563b2df285ab89e76c82f91e1a1a49c1e/cmd/wsh/cmd/wshcmd-setbg.go#L99-L135","documentation":"`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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\nBG=\"\" ; wsh setbg \"$BG\"          # empty -> error\n// after\nwsh setbg --opacity 0.5           # or pass a real path/color argument","handlingStrategy":"validation","validationCode":"if len(args) == 0 && opacityFlag == nil && !clearFlag && borderColor == \"\" && activeBorderColor == \"\" {\n    return errors.New(\"setbg needs an image path or color, or a modifier flag like --opacity/--clear\")\n}","typeGuard":null,"tryCatchPattern":"if err := run(); err != nil {\n    if strings.Contains(err.Error(), \"requires an image path or color value\") { /* print usage or apply a default */ }\n}","preventionTips":["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."],"tags":["cli","validation","usage","argument"],"backgroundTag":"missing-required-argument","analyzedSha":"a4447c1563b2df285ab89e76c82f91e1a1a49c1e","analyzedAt":"2026-09-01T15:26:23.972Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}