kovidgoyal/kitty · error

invalid previewer specification: %#v with error: %w

Error message

invalid previewer specification: %#v with error: %w

What it means

A previewer entry in the choose-files config failed shell-style tokenization by shlex.Split — the spec string has unbalanced quotes or invalid shell syntax, so it cannot be split into prefix:pattern plus command.

Source

Thrown at kittens/choose_files/main.go:297

type previewer struct {
	cmdline      []string
	pattern      string
	use_mimetype bool
}

func (p previewer) matches(fname, mt string) bool {
	q := utils.IfElse(p.use_mimetype, mt, fname)
	matched, err := filepath.Match(p.pattern, q)
	return matched && err == nil
}

var previewers []previewer

func load_previewers(cfg *Config) (err error) {
	for _, spec := range cfg.Previewer {
		parts, err := shlex.Split(spec)
		if err != nil {
			return fmt.Errorf("invalid previewer specification: %#v with error: %w", spec, err)
		}
		if len(parts) < 2 {
			return fmt.Errorf("invalid previewer specification: %#v with error: no command specified", spec)
		}
		prefix, pattern, found := strings.Cut(parts[0], ":")
		if !found {
			return fmt.Errorf("invalid previewer specification: %#v with error: no prefix in pattern specification", spec)
		}
		previewers = append(previewers, previewer{parts[1:], pattern, prefix == "mime"})
	}
	return
}

func load_config(opts *Options) (ans *Config, err error) {
	ans = NewConfig()
	p := config.ConfigParser{LineHandler: ans.Parse}
	err = p.LoadConfig("choose-files.conf", opts.Config, opts.Override)
	if err != nil {

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Fix the quoting in the previewer spec so shlex can parse it (balance all quotes)
2. Test the spec string with a shell: echo of the command should tokenize cleanly
3. Simplify the spec: avoid nested quotes, use a wrapper script instead

Example fix

# before
--previewer 'mime:image/* chafa -s {{columns}}x{{rows}} '"'"'file with spaces'"'"''
# after
--previewer 'mime:image/* preview-image.sh'

if _, err := shlex.Split(spec); err != nil { return fmt.Errorf("bad quoting in previewer spec: %v", err) }

When it happens

Trigger: Configuring --previewer 'name:{pattern} cmd' where the spec contains unterminated quotes or stray shell metacharacters that shlex rejects.

Common situations: Quoting mistakes in kitty.conf or CLI --previewer arguments, e.g. embedding a command with an unmatched single quote.

Related errors

• invalid previewer specification: %#v with error: no command
• invalid previewer specification: %#v with error: no prefix i
• invalid value %s in video_preview
• This should be run as kitten broadcast
• No option named: {k}

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