kovidgoyal/kitty · warning

ZSH anchor based matching active, cannot complete. Turn it o

Error message

ZSH anchor based matching active, cannot complete. Turn it off by setting zstyle :completion: to something that does not use anchors in your ~/.zshrc

What it means

kitty's shell completion for zsh detected that the user's zstyle matcher-list configuration uses anchor-based matching (e.g. 'r:|[._-]=* r:|=* l:|=*', common in Debian's default zshrc). kitty's completion generator cannot produce working candidates under those matcher types, so it aborts completion instead of emitting broken results.

Source

Thrown at tools/cli/zsh.go:69

var debugprintln = tty.DebugPrintln
var _ = debugprintln

func zsh_input_parser(data []byte, shell_state map[string]string) ([][]string, error) {
	matcher := shell_state["_matcher"]
	q := ""
	if matcher != "" {
		q = strings.Split(strings.ToLower(matcher), ":")[0][:1]
	}
	if q != "" && strings.Contains("lrbe", q) {
		// this is zsh anchor based matching
		// https://zsh.sourceforge.io/Doc/Release/Completion-Widgets.html#Completion-Matching-Control
		// can be specified with matcher-list and some systems do it by default,
		// for example, Debian, which adds the following to zshrc
		// zstyle ':completion:*' matcher-list '' 'm:{a-z}={A-Z}' 'm:{a-zA-Z}={A-Za-z}' 'r:|[._-]=* r:|=* l:|=*'
		// For some reason that I dont have the
		// time/interest to figure out, returning completion candidates for
		// these matcher types break completion, so just abort in this case.
		return nil, fmt.Errorf("ZSH anchor based matching active, cannot complete. Turn it off by setting zstyle :completion: to something that does not use anchors in your ~/.zshrc")
	}
	return shell_input_parser(data, shell_state)
}

func (self *Match) FormatForCompletionList(max_word_len int, f *markup.Context, screen_width int) string {
	word := self.Word
	desc := self.Description
	if desc == "" {
		return word
	}
	word_len := wcswidth.Stringwidth(word)
	line, _, _ := strings.Cut(strings.TrimSpace(desc), "\n")
	desc = f.Prettify(line)

	multiline := false
	max_desc_len := screen_width - max_word_len - 3
	if word_len > max_word_len {
		multiline = true

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Edit your ~/.zshrc (or comment the Debian system zshrc line) and change zstyle ':completion:*' matcher-list to remove 'r:|=*' / 'l:|=*' anchor patterns, e.g. zstyle ':completion:*' matcher-list '' 'm:{a-z}={A-Z}' 'm:{a-zA-Z}={A-Za-z}'
2. Restart zsh or start a new shell after editing
3. If you need those matchers for other commands, scope them narrowly instead of ':completion:*'

Example fix

# before
zstyle ':completion:*' matcher-list '' 'm:{a-z}={A-Z}' 'r:|[._-]=* r:|=* l:|=*'
# after
zstyle ':completion:*' matcher-list '' 'm:{a-z}={A-Z}' 'm:{a-zA-Z}={A-Za-z}'

if grep -q 'r:|=*' <(zstyle -L ':completion:*' matcher-list) 2>/dev/null; then echo 'disable anchor matchers before using kitty completion'; fi

When it happens

Trigger: zsh_input_parser inspects the completion context data and detects anchor matchers in the matcher-list zstyle; it returns this error and completion produces nothing.

Common situations: Debian/Ubuntu systems whose /etc/zsh/zshrc ships anchor-based matcher-list entries, or users who copied popular zshrc snippets (e.g. 'r:|[._-]=* r:|=* l:|=*') into ~/.zshrc, then invoke kitty's zsh completion.

Related errors

• Failed to compile word_regex %q: %w
• This must be run as kitten ask
• This should be run as kitten broadcast
• This must be run as kitten choose-files
• Pipe to kitten was broken while sending data to it

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