kovidgoyal/kitty · error

The --place option can only be used with a single image, not

Error message

The --place option can only be used with a single image, not %d

What it means

The --place option positions one image at a specific grid cell, so it only makes sense with exactly one image. It was given while more than one image (after directory expansion) was being displayed.

Source

Thrown at kittens/icat/main.go:257

			return 1, err
		}
	case opts.Clear:
		cc := &graphics.GraphicsCommand{}
		cc.SetAction(graphics.GRT_action_delete).SetDelete(graphics.GRT_free_visible)
		if err = cc.WriteWithPayloadTo(os.Stdout, nil); err != nil {
			return 1, err
		}
	}
	if screen_size.Xpixel == 0 || screen_size.Ypixel == 0 {
		return 1, fmt.Errorf("Terminal does not support reporting screen sizes in pixels, use a terminal such as kitty, WezTerm, Konsole, etc. that does.")
	}

	items, err := process_dirs(args...)
	if err != nil {
		return 1, err
	}
	if opts.Place != "" && len(items) > 1 {
		return 1, fmt.Errorf("The --place option can only be used with a single image, not %d", len(items))
	}
	files_channel = make(chan input_arg, len(items))
	for i, ia := range items {
		ia.index = i
		files_channel <- ia
	}
	num_of_items = len(items)
	output_channel = make(chan *image_data, 1)
	keep_going = &atomic.Bool{}
	keep_going.Store(true)
	if !opts.DetectSupport && num_of_items > 0 {
		num_workers := utils.Max(1, utils.Min(num_of_items, runtime.NumCPU()))
		for range num_workers {
			go run_worker()
		}
	}

	passthrough_mode := no_passthrough

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Pass a single image file with --place
2. Drop --place when displaying multiple images (use --grid instead)
3. If a directory was passed, ensure it contains exactly one image

Example fix

// before
kitten icat --place 3x2@2x1 ./imgs/
// after
kitten icat --place 3x2@2x1 ./imgs/only.png

files, _ := filepath.Glob(pattern)
if place != "" && len(files) > 1 { log.Fatal("--place requires exactly one image") }

When it happens

Trigger: kitten icat --place 3x2@2x1 img1.png img2.png, or passing a directory containing multiple images with --place.

Common situations: Globbing a directory (icat expands directories to their images); shell expanding *.png into several files.

Related errors

• Invalid size specification: %s
• {spec} is not a valid setting
• {parts[0]} is not a valid edge specification
• {parts[1]} is not a number
• No colors specified

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