kovidgoyal/kitty · error

Failed to run custom processor %#v with error: %w\n%s

Error message

Failed to run custom processor %#v with error: %w\n%s

What it means

The hints kitten ran a CustomizeProcessing custom-processor program; the program exited non-zero (or failed to start) and its stderr is appended to the error. The custom processor is expected to read hint options on stdin and emit JSON marks on stdout.

Source

Thrown at kittens/hints/marks.go:681

		return nil
	}

	if opts.CustomizeProcessing != "" {
		cmd := exec.Command(utils.KittyExe(), append([]string{"+runpy", "from kittens.hints.main import custom_marking; custom_marking()"}, cli_args...)...)
		cmd.Stdin = strings.NewReader(sanitized_text)
		stdout, stderr := bytes.Buffer{}, bytes.Buffer{}
		cmd.Stdout, cmd.Stderr = &stdout, &stderr
		err = cmd.Run()
		if err != nil {
			var e *exec.ExitError
			if errors.As(err, &e) && e.ExitCode() == 2 {
				err = run_basic_matching()
				if err != nil {
					return
				}
				goto process_answer
			} else {
				return "", nil, nil, fmt.Errorf("Failed to run custom processor %#v with error: %w\n%s", opts.CustomizeProcessing, err, stderr.String())
			}
		}
		ans = make([]Mark, 0, 32)
		err = json.Unmarshal(stdout.Bytes(), &ans)
		if err != nil {
			return "", nil, nil, fmt.Errorf("Failed to load output from custom processor %#v with error: %w", opts.CustomizeProcessing, err)
		}
		err = adjust_python_offsets(sanitized_text, ans)
		if err != nil {
			return "", nil, nil, fmt.Errorf("Custom processor %#v produced invalid mark output with error: %w", opts.CustomizeProcessing, err)
		}
	} else if opts.Type == "hyperlink" {
		ans = hyperlinks
	} else if opts.Type == "word" {
		ans = mark_words(sanitized_text, opts)
	} else {
		err = run_basic_matching()
		if err != nil {

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Run the custom processor manually with the JSON options on stdin to see the appended stderr traceback
2. Fix the exception in the custom processor script
3. Ensure the path in CustomizeProcessing is executable and its kitty version matches the mark JSON schema

Example fix

# before
echo "$opts" | my_processor.py  # crashes
# after
echo "$opts" | python3 -c 'import sys,json; d=json.load(sys.stdin); print("[]")'

if err := checkExecutable(opts.CustomizeProcessing); err != nil { /* fall back to builtin matching */ }

Wrap find_marks; on 'Failed to run custom processor' log the embedded stderr and fall back to run_basic_matching().

When it happens

Trigger: Setting opts.CustomizeProcessing to a program that crashes, exits non-zero, or is not executable; the goto process_answer path shows a special-cased fallback exists only for the built-in matching path.

Common situations: Custom hint processor script has a Python exception, wrong interpreter shebang, missing file permission, or incompatible schema version between kitty and the script.

Related errors

• Failed to load output from custom processor %#v with error:
• Custom processor %#v produced invalid mark output with error
• Failed to convert {src_path} to RGBA data with error: {cp.st
• You are missing the {args[0]} program needed to generate the
• Failed to compile the regex pattern: %#v with error: %w

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