What causes "Invalid value for --background: %w" in kovidgoyal/kitty?

Use a standard color name or #rrggbb / #rgb hex form

Invalid value for --background: %w

Error message

Invalid value for --background: %w

What it means

icat's --background option (other than '' or 'none') is parsed with style.ParseColor; an unparseable color string yields this error.

Source

Thrown at kittens/icat/main.go:81

var fit_mode fit_t

func send_output(imgd *image_data) {
	output_channel <- imgd
}

func parse_mirror() (err error) {
	flip = opts.Mirror == "both" || opts.Mirror == "vertical"
	flop = opts.Mirror == "both" || opts.Mirror == "horizontal"
	return
}

func parse_background() (err error) {
	if opts.Background == "" || opts.Background == "none" {
		return nil
	}
	col, err := style.ParseColor(opts.Background)
	if err != nil {
		return fmt.Errorf("Invalid value for --background: %w", err)
	}
	remove_alpha = &imaging.NRGBColor{R: col.Red, G: col.Green, B: col.Blue}
	return
}

func parse_z_index() (err error) {
	val := opts.ZIndex
	var origin int32
	if strings.HasPrefix(val, "--") {
		origin = -1073741824
		val = val[1:]
	}
	i, err := strconv.ParseInt(val, 10, 32)
	if err != nil {
		return fmt.Errorf("Invalid value for --z-index with error: %w", err)
	}
	z_index = int32(i) + origin
	return

View on GitHub (pinned to 6d5d0c4406)

Solutions

Use a standard color name or #rrggbb / #rgb hex form
Check for typos and a leading '#' on hex values
Use --background none to disable

Example fix

# before
kitty +kitten icat --background=#ff00zz img.png
# after
kitty +kitten icat --background=#ff0000 img.png

Defensive patterns

Strategy: validation

Validate before calling

if _, err := style.ParseColor(opts.Background); err != nil { /* reject early with usage hint */ }

Prevention

Use #rrggbb or documented color names
Test color args in a wrapper before invoking icat

When it happens

Trigger: --background with an invalid color name or malformed hex, e.g. --background=#GGG or --background=chartreuse2-nope.

Common situations: Typos in color names, missing '#' on hex values, or using CSS color syntax the parser doesn't support.

Related errors

AI-assisted analysis of kovidgoyal/kitty@6d5d0c4406 (2026-08-27). Data as JSON: /api/errors/89e0b8d2cc9729a7. Report an issue: GitHub.