kovidgoyal/kitty · error

Invalid value for --z-index with error: %w

Error message

Invalid value for --z-index with error: %w

What it means

--z-index takes an optionally '--'-prefixed integer (prefix sets a negative origin of -1073741824); the remainder must parse as a 32-bit int. ParseInt failure produces this error.

Source

Thrown at kittens/icat/main.go:96

	}
	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
}

func parse_fit() (err error) {
	switch strings.ToLower(opts.Fit) {
	case "width":
		fit_mode = fit_width
	case "height":
		fit_mode = fit_height
	case "none", "neither":
		fit_mode = fit_none
	case "both":
		fit_mode = fit_both
	default:
		return fmt.Errorf("unknown fit specification: %#v", opts.Fit)
	}

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Pass a plain integer: --z-index=5
2. For negative stacking use the '--' prefix form as documented, not '-5'
3. Keep magnitude within int32 range

Example fix

# before
kitty +kitten icat --z-index=-5 img.png
# after
kitty +kitten icat --z-index=--5 img.png

if _, err := strconv.ParseInt(strings.TrimPrefix(val, "-"), 10, 32); err != nil { /* reject before running icat */ }

When it happens

Trigger: --z-index=abc, --z-index=1.5, or a value overflowing int32 range.

Common situations: Passing a float or non-numeric value; misunderstanding that only integers (optionally prefixed with '--' for negative origin) are accepted.

Related errors

• Invalid value for --background: %w
• unknown fit specification: %#v
• Invalid --place specification: %s
• Unknown extra argument(s) supplied to {command.name}
• 'size' must be a non-negative integer

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