# 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. |