What causes "Unknown map option: %s" in kovidgoyal/kitty?

Unknown map option: %s

Error message

Unknown map option: %s

What it means

While parsing a map directive's --flag=value form, ParseMap hit a flag name it does not recognize (only allow_fallback is supported) and rejected it.

Source

Thrown at tools/config/utils.go:293

		if !found {
			return nil, fmt.Errorf("No key specified after flag %s", flag)
		}
		rest = strings.TrimSpace(rest)
		if name, value, ok := strings.Cut(flag, "="); ok {
			// --flag=value form
			name = strings.ReplaceAll(name[2:], "-", "_")
			switch name {
			case "allow_fallback":
				if err := validateAllowFallback(value); err != nil {
					return nil, err
				}
				if value == "none" {
					allow_fallback = ""
				} else {
					allow_fallback = value
				}
			default:
				return nil, fmt.Errorf("Unknown map option: %s", flag)
			}
		} else {
			// --flag value form (space-separated)
			name := strings.ReplaceAll(flag[2:], "-", "_")
			switch name {
			case "allow_fallback":
				value, after, has_more := strings.Cut(rest, " ")
				if !has_more {
					return nil, fmt.Errorf("No key specified after %s %s", flag, value)
				}
				if err := validateAllowFallback(value); err != nil {
					return nil, err
				}
				if value == "none" {
					allow_fallback = ""
				} else {
					allow_fallback = value
				}

View on GitHub (pinned to 6d5d0c4406)

Solutions

Remove the unsupported flag
Use --allow-fallback as the only currently supported flag
Consult the map directive docs for the kitty version in use

Example fix

# before
map --repeat=3 ctrl+a 1
# after
map ctrl+a 1

Defensive patterns

Strategy: validation

Validate before calling

const, value, ok := strings.Cut(strings.TrimPrefix(flag, "--"), "=")
_ = value
if !ok || const != "allow-fallback" && const != "allow_fallback" { return fmt.Errorf("unsupported flag %q", flag) }

Type guard

func isKnownMapFlag(f string) bool { n := strings.ReplaceAll(strings.TrimPrefix(strings.SplitN(f, "=", 2)[0], "--"), "-", "_"); return n == "allow_fallback" }

Prevention

Only use --allow-fallback on map lines
Check kitty docs for the running version before adding flags

When it happens

Trigger: `map --foo=bar ctrl+a 1` in a config file — any --flag=value other than --allow-fallback.

Common situations: Copy-pasting map lines from newer/older kitty docs that support different flags, or guessing flag names.

Related errors

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