You must specify exactly two files/directories to compare

Error message

You must specify exactly two files/directories to compare

What it means

This error is raised by the diff kitten's main function when the command line does not contain exactly two positional arguments. The diff kitten is invoked as `kitty +kitten diff <left> <right>` and the argument count is validated after config loading, before any diffing starts. Any invocation with zero, one, or more than two paths fails immediately with exit code 1.

Source

Thrown at kittens/diff/main.go:127

func get_remote_file(path string) (string, error) {
	if strings.HasPrefix(path, "ssh:") {
		parts := strings.SplitN(path, ":", 3)
		if len(parts) == 3 {
			return get_ssh_file(parts[1], parts[2])
		}
	}
	return path, nil
}

func main(_ *cli.Command, opts_ *Options, args []string) (rc int, err error) {
	opts = opts_
	conf, err = load_config(opts)
	if err != nil {
		return 1, err
	}
	if len(args) != 2 {
		return 1, fmt.Errorf("You must specify exactly two files/directories to compare")
	}
	if err = set_diff_command(conf.Diff_cmd); err != nil {
		return 1, err
	}
	switch conf.Color_scheme {
	case Color_scheme_light:
		use_light_colors = true
	case Color_scheme_dark:
		use_light_colors = false
	case Color_scheme_auto:
		use_light_colors = false
	}
	init_caches()
	defer func() {
		for tdir := range remote_dirs {
			os.RemoveAll(tdir)
		}
	}()

View on GitHub (pinned to 6d5d0c4406)

Solutions

Check the invocation: it must be exactly `kitty +kitten diff <path1> <path2>`.
If scripting, quote variables and verify they are non-empty before calling the kitten.
If you meant to diff git revisions, expand them to two files/directories first (e.g. via git worktree or temp checkouts) and pass those paths.

Example fix

# before
kitty +kitten diff "$left"

# after
kitty +kitten diff "$left" "$right"

Defensive patterns

Strategy: validation

Validate before calling

// Go: validate before invoking the kitten
if len(paths) != 2 {
    return fmt.Errorf("need exactly two paths, got %d", len(paths))
}
for _, p := range paths {
    if strings.TrimSpace(p) == "" {
        return fmt.Errorf("empty path argument")
    }
}
cmd := exec.Command("kitty", "+kitten", "diff", paths[0], paths[1])

Try / catch

Check the exit status and stderr of the kitty process; a message starting with 'You must specify exactly two' is a usage bug in the caller, so fix the invocation rather than retrying.

Prevention

Always pass exactly two quoted, non-empty path arguments.
Validate argument count in wrapper scripts before exec.
Read the kitten's stderr to distinguish usage errors from real failures.

When it happens

Trigger: Running `kitty +kitten diff` with no arguments, one path, or three or more paths; passing flags after positional args incorrectly so the parser sees the wrong number of positionals; wrapping the kitten in a script that drops or adds an argument.

Common situations: Shell scripts that pass unquoted/unexpanded variables (e.g. an empty $file variable) so one path disappears; users assuming the kitten diffs against a git ref or STDIN like `git diff`; typos where a flag is passed without its value, shifting positional parsing.

Related errors

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