fish_command_not_found - what to do when a command wasn't found

Metadata

Field	Value
Institute	Molodetz Institute — Research & Retrieval Division
Subject	shell-multiplexer-auto-attach
Document type	Source Dossier
Tier	1
Source title	fish_command_not_found - what to do when a command wasn't found
Source URL	https://fishshell.com/docs/4.8/cmds/fish_command_not_found.html
Source publisher / author	fish-shell project (fishshell.com)
Source type	vendor docs
Source date (published)	Unknown — not stated
Date researched	2026-10-10
Researched by	tai (agent), model: Claude Sonnet 5, on behalf of retoor
Research method	web search synthesis
Confidence	High
Status	Active

Summary

fish's analogue of bash's command_not_found_handle/zsh's command_not_found_handler is a plain user-definable function named fish_command_not_found, called whenever fish fails to find a command. It receives the attempted command line as $argv (one token per arg, so $argv[1] is the missing command name), was introduced in fish 3.2.0, and falls back to fish's own default error message if left undefined or if the function explicitly calls __fish_default_command_not_found_handler.

Key findings

Defined with ordinary fish function syntax: function fish_command_not_found; ...; end, no special registration step required beyond defining the function (typically in config.fish or an autoloaded ~/.config/fish/functions/fish_command_not_found.fish file).
$argv holds the full attempted command line as separate tokens, directly analogous to bash's "$@" inside command_not_found_handle.
Introduced in fish 3.2.0; versions before that used a fish_command_not_found event instead of a function, so a handler meant to support pre-3.2 fish needs a dual event+function definition — not a concern for this project, which only needs to support a function since its own tai.py requires modern Python 3 anyway and fish 3.2 (2020) predates any realistic target.
Leaving the function undefined, or having it call __fish_default_command_not_found_handler, reproduces fish's normal plain error message — useful as the explicit fallback behavior if tai's own hook is ever uninstalled.

Pros / strengths

Official, current vendor documentation, consistent across every mirrored version from 3.2 through 4.x found in this search — a stable, non-moving target to build on.
Directly structurally parallel to bash/zsh's own mechanism (one function, one argv), which kept the tai.py implementation simple: same body shape ("$HOME/.local/bin/tai.py" $argv) as the bash/zsh blocks, just fish function syntax instead of a shell function definition.

Cons / limitations / caveats

Unlike bash's command_not_found_handle/zsh's command_not_found_handler, which are ordinary shell functions sourced from any rc file read at the right time, fish's function must specifically be named fish_command_not_found — fish does not look for an alternately-named function for this purpose.

Relevance to tai

This is the exact mechanism FISH_NOTFOUND_BLOCK in tai.py implements: a function fish_command_not_found; "$HOME/.local/bin/tai.py" $argv; end block written into config.fish by upsert_fish_hook_block/op_fish_hook, directly parallel to the existing bash/zsh blocks.

Changelog

Date	Change
2026-10-10	Initial dossier created.

3.4 KiB Raw Blame History