What causes "Must specify at most one output file" in kovidgoyal/kitty?

Pass zero arguments to write PNG to stdout, or exactly one output path

Must specify at most one output file

Error message

Must specify at most one output file

What it means

kitty @ screenshot accepts at most one positional argument (an output file path). More than one file was given on the command line, which is rejected before the request is sent.

Source

Thrown at tools/cmd/at/screenshot.go:25

	"os"
	"path/filepath"

	"github.com/emmansun/base64"
	"github.com/kovidgoyal/kitty/tools/utils"
)

func screenshot_handle_response(data []byte) error {
	png_data, err := base64.StdEncoding.DecodeString(string(data))
	if err != nil {
		return err
	}
	_, err = os.Stdout.Write(png_data)
	return err
}

func read_screenshot_args(io_data *rc_io_data, args []string) (func(io_data *rc_io_data) (bool, error), error) {
	if len(args) > 1 {
		return nil, fmt.Errorf("%s", "Must specify at most one output file")
	}
	if len(args) == 0 {
		// kitty writes the screenshot directly to the output file when one is
		// given (it runs on the same computer as kitty), so a custom response
		// handler is only needed to write the PNG data to STDOUT.
		io_data.handle_response = screenshot_handle_response
	}
	return func(io_data *rc_io_data) (bool, error) {
		// io_data.rc.Payload is only populated after this generator is created,
		// so the payload field must be set here rather than above.
		if len(args) == 1 {
			path, err := filepath.Abs(utils.Expanduser(args[0]))
			if err != nil {
				return false, fmt.Errorf("%s is not a valid path with error: %w", args[0], err)
			}
			set_payload_string_field(io_data, "Output_path", path)
		}
		return true, nil

View on GitHub (pinned to 6d5d0c4406)

Solutions

Pass zero arguments to write PNG to stdout, or exactly one output path
To capture multiple windows, invoke the command once per window using --match
Quote arguments so globs don't expand unexpectedly

Example fix

# before
kitty @ screenshot win1.png win2.png
# after
kitty @ screenshot --match id:1 win1.png && kitty @ screenshot --match id:2 win2.png

Defensive patterns

Strategy: validation

Validate before calling

if len(args) > 1 { return errors.New("Must specify at most one output file") }

Type guard

func validScreenshotArgs(args []string) bool { return len(args) <= 1 }

Prevention

Pass at most one output path
Loop with --match to capture multiple windows

When it happens

Trigger: Running e.g. 'kitty @ screenshot a.png b.png' — len(args) > 1 in read_screenshot_args.

Common situations: Users trying to screenshot multiple windows by listing files, or shell glob expansion producing several paths.

Related errors

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