zsh-users mailing list: command_not_found_handler autoload example (Bart Schaefer, 2015)

Metadata

Field	Value
Institute	Molodetz Institute — Research & Retrieval Division
Subject	shell-multiplexer-auto-attach
Document type	Source Dossier
Tier	1
Source title	Zsh Mailing List Archive (zsh-users, 2015, msg00931)
Source URL	https://www.zsh.org/mla/users/2015/msg00931.html
Source publisher / author	Bart Schaefer, via the zsh-users mailing list (zsh.org)
Source type	forum thread
Source date (published)	2015 (exact date not stated in the search result)
Date researched	2026-10-10
Researched by	tai (agent), model: Claude Sonnet 5, on behalf of retoor
Research method	web search synthesis
Confidence	Medium
Status	Active

Summary

A zsh core contributor's own worked example of command_not_found_handler: a zsh-recognized function name that fires when zsh's normal $fpath/$path lookup fails to find a command, with the example showing it dynamically registering (FPATH=$PWD; autoload +X $missing_command) and running a function on the fly before falling through to the usual error.

Key findings

command_not_found_handler is a plain zsh function definition, recognized by name — the zsh analogue of bash's command_not_found_handle, differing only in the handler/handle suffix. No autoload directive is required just to make zsh call it; autoload is only used inside the example body for its own dynamic-function-loading trick, which is unrelated to the hook mechanism itself being active.
The handler runs after the parent shell has already forked for the failed command, per Bart Schaefer's own note in the thread — so anything the handler loads or defines does not persist back into the parent shell's own function table.
The example demonstrates autoload -X being used inside a handler for a specific advanced use case (lazy-loading an unknown function from the current directory); this is a feature of the example's specific technique, not a requirement for using command_not_found_handler at all.

Pros / strengths

Directly from a zsh core contributor, carrying real authority on the mechanism's actual semantics (the fork-before-handler timing detail in particular is not the kind of thing casual documentation usually states explicitly).

Cons / limitations / caveats

The worked example itself is solving a different, more advanced problem (dynamic function loading) than tai's simple delegate-to-a-binary use case; only the top-level fact (the handler's name and that it's a plain function) was load-bearing for this project, not the autoload trick inside it.

Relevance to tai

Confirms the exact function name (command_not_found_handler, not _handle) that ZSH_NOTFOUND_BLOCK in tai.py defines, and confirms no special autoload/registration step is needed beyond the function definition itself — consistent with the simple, bash-parallel block tai.py actually writes.

Changelog

Date	Change
2026-10-10	Initial dossier created.

3.1 KiB Raw Blame History