Claude Code Stop Hook Error: 294 Issues, 10 Probes, 6 Fired

The line is Stop hook error occurred · ctrl+o to see, and it is the same red line for six different things. In 30 days my fleet ran Stop hooks 7,248 times and never produced it once. So I built ten Stop hooks that were supposed to fail, ran each through claude -p on 2.1.263, and read what came out. Six of the ten raised the notice. Two of those six were hooks doing exactly what the documentation says to do.

Below: what the 294 GitHub issues that mention the phrase actually contain, what each of my ten probes recorded, and which cases are a bug in your hook versus a label you can ignore.

294 issues, one label

I pulled every issue in anthropics/claude-code whose title or body contains "Stop hook error" on 2026-09-11: 294 results, 31 still open. 135 of them quote a literal Stop hook error: line, and the text after the colon is where the actual causes live. I grouped the bodies by the first message pattern they match.

Message family	Issues	Still open	Example
No quoted message (the phrase appears in discussion)	169	25	#85935
Failed with non-blocking status code: other	51	1	#43024
Shell: No such file or directory / not found	17	1	#64064
JSON validation failed	14	1	#62246
Block reason rendered as an error	13	0	#84385
Evaluator API error (Prompt is too long, 400)	10	3	#58192
posix_spawn / ENOENT	8	0	#37069
No stderr output	5	0	#59939
Node module or runtime error	4	0	#64420
TabManager not available	3	0	#35592

Counting the raw strings after Stop hook error: across all bodies gives the same shape from the other side: Failed with non-blocking status code: Error occurred while executing hook command appears 16 times, JSON validation failed 15, /bin/bash: 9, /bin/sh: 8, Hook evaluator API error: Prompt is too long 5, No stderr output 4, node:internal/modules/ 4. The month with the most reports was March 2026 with 70, when the plugin cache path and execute-bit bugs (#36035, #39798) were live. Most of these families are the hook not running at all: a path that moved, a shell that was not there, a node that was not on PATH. The hook did not fail. It never started. That is the family I wrote about in what 172 plugins cost, from the other direction.

Ten hooks built to fail

The issue corpus tells you what people saw. It does not tell you what a given exit code and stdout shape produce on the current build, so I measured that. Each probe is a one-line hook.sh injected through --settings as the only user-configured Stop hook, run with claude -p "Reply with exactly the single word OK" on 2.1.263, sonnet, --output-format stream-json --verbose --max-turns 3. Ten runs cost $0.92. I read two surfaces for each: the stream, where the notice is a system record with "key":"stop-hook-error", and the session transcript, where the hook result is an attachment record with a hook_* type.

Hook does	Notice	Transcript record	Text recorded
exit 1, stderr boom	yes	hook_non_blocking_error	Failed with non-blocking status code: boom from stderr
exit 1, no stderr	yes	hook_non_blocking_error	Failed with non-blocking status code: No stderr output
path does not exist	yes	hook_non_blocking_error, exit 127, 5 ms	Failed with non-blocking status code: /bin/sh: …: No such file or directory
exit 0, stdout {"decision": }	yes	hook_non_blocking_error, exit 0	Hook output looks like a JSON object but is not valid JSON … Emit the payload with a JSON encoder (jq, ConvertTo-Json, json.dumps)
exit 0, {"decision":"block","reason":…}	yes	hook_blocking_error	model receives Stop hook feedback: and continues
exit 2, stderr reason	yes	none for the hook itself	model receives Stop hook feedback: [path]: … and continues
exit 0, {"decision":"approve"}	no	hook_success	ignored
exit 0, hookSpecificOutput.additionalContext	no	hook_success	model continues, no label
exit 0, JSON inside a ```json fence	no	hook_success	stored as text, no block
exit 0, stderr only	no	hook_success	stderr stored, nothing shown

Two of the six are not errors

The decision: "block" probe and the exit 2 probe both did their job. The model got a user turn reading Stop hook feedback:\nSay DONE before stopping., replied DONE, and the run ended cleanly on the second turn. The stream still carried "key":"stop-hook-error" with priority: "immediate", and the transcript for the JSON version holds a hook_blocking_error attachment whose rendered form is <system-reminder>Stop hook blocking error from command: "…": Say DONE before stopping.</system-reminder>. Same payload, three labels: feedback to the model, blocking error in the transcript, error occurred on screen.

This is the family that #84385, #34600, #62139 and #12667 are about, filed between November 2025 and August 2026. #34600 was closed not_planned on 2026-06-01; #84385 was closed completed on 2026-08-17 after a maintainer reproduced it. On 2.1.263 the notice still fires for both block paths. The only continuation mechanism that runs without the label is hookSpecificOutput.additionalContext, added in 2.1.163 per the changelog, and the hooks reference now says so in as many words: "the transcript labels it Stop hook feedback and no hook error notification is shown." My probe agrees: hook_success, no notice, model continued.

One silent case that should not be

The reference says the only valid decision value on Stop is "block", and that exit 0 with JSON that fails schema validation is a non-blocking error with a notice. My probe printed {"decision":"approve","reason":"x"} and got nothing: hook_success, stdout stored verbatim, no notice, model stopped normally. If you copied a PreToolUse hook and left approve in it, the Stop version fails open and tells no one. Compare the parse-error probe, {"decision": }, which since 2.1.248 gets a full paragraph: Hook output looks like a JSON object but is not valid JSON, then the advice to emit through jq or json.dumps. Before 2.1.248 that stdout was treated as plain text, which is the reference's own footnote and matches the 2.0.28 report in #10463 where a hook with zero output still drew the label.

Markdown-fenced JSON is the other quiet failure. A hook that prints ```json around a valid block decision is stored as text and blocks nothing, because stdout has to start with { and end with } to be parsed at all. That is exactly the shape the built-in /goal evaluator emitted, which is why the autocomplete for this query has a goal stop hook error json validation failed variant: #58558 and #62246 both describe the prompt-type evaluator returning fenced JSON or markdown and every turn ending with Stop hook error: JSON validation failed. The changelog entry for 2.1.97 and 2.1.98 says evaluator API errors were being displayed as JSON validation failed instead of the real message, and #62246 was closed on 2026-08-17, with comments reproducing it on 2.1.152, 2.1.178 and 2.1.195 in between. If you are on one of those builds and using /goal, the label is the evaluator's, not yours.

What my fleet's 7,248 clean runs look like

The baseline matters because it says what a healthy Stop hook leaves behind. Across 2,404 sessions in the last 30 days, excluding this one and the probes, the transcripts hold 92,860 hook_success attachments and every one has exitCode: 0. 7,248 of them are Stop hooks across 1,987 sessions: three plugin scripts at 2,129 runs each, a terminal integration hook at 709, an older one at 152. 7,096 of the 7,248 wrote a JSON object to stdout. Zero wrote anything to stderr. Median duration was 118 ms, the 95th percentile 198 ms, the slowest 3,757 ms, and the sum of all of them was 899 seconds of the month. The only hook_cancelled records, three of them, were SessionStart hooks hitting a 5,000 ms timeout, which is the same two-surface story as the 130,193-run census: the hook that fires most is the one you never see.

So the answer to "how often does a Stop hook error happen in normal operation" is, for this fleet, never in 7,248 runs. Every one of the six notices in this post required a hook that exited non-zero, printed broken JSON, or asked the model to keep going. If your fleet shows the label, one of those three happened, and the transcript says which.

Reading it without ctrl+o

Headless runs have no ctrl+o. The record is in the session transcript, and the type name is the diagnosis:

grep -o '"type":"hook_[a-z_]*"' ~/.claude/projects/*/*.jsonl | sort | uniq -c
# hook_non_blocking_error  -> exit code or parse failure; read "stderr" in the same record
# hook_blocking_error      -> a decision:"block" that worked; not a bug
# hook_success             -> exit 0, stdout stored verbatim, even if it was wrong JSON

For the non-blocking case the stderr field holds the full first line, including the Failed with non-blocking status code: prefix and the shell's own message, so a missing interpreter reads as /bin/sh: …: No such file or directory with exitCode: 127 and a durationMs of 5. A hook that ran for 300 ms and exited 1 is your script. A hook that ran for 5 ms is your path. The --debug-file flag I settled on in the debug mode post captures full stderr rather than the first line, if the first line is not enough.

The hook shape that produced no notice and still steered the model is the one I would ship:

#!/bin/bash
input=$(cat)
if printf '%s' "$input" | grep -q '"stop_hook_active":true'; then exit 0; fi
jq -n --arg msg "Run the test suite before finishing." \
  '{hookSpecificOutput:{hookEventName:"Stop",additionalContext:$msg}}'

The stop_hook_active guard is what keeps the model from being told the same thing eight times; 2.1.143 added a cap of eight consecutive blocks, overridable with CLAUDE_CODE_STOP_HOOK_BLOCK_CAP, after #67665-style loops. The jq -n is the encoder the parse-error message asks for. And additionalContext instead of decision: "block" is the difference between a session log that reads clean and one that reads like a fleet on fire. Whether a notice belongs on intentional blocks is a design argument the issues have been having for ten months. Whether your hook exited 127 is not. The settings layering that decides which file the hook is even loaded from is a separate post, and so is the memory reminder that arrives as hook context. The launchd runner and the prompt these hooks fire around are in the Playbook; the guard above is not in there yet.

Sources and method: the issue census is a GitHub search for the exact phrase "Stop hook error" in anthropics/claude-code on 2026-09-11 (294 results, bodies classified by the first message pattern matched, so the "no quoted message" row includes issues that only discuss the phrase). The ten probes ran on Claude Code 2.1.263 with sonnet in a throwaway directory, one user-configured Stop hook each via --settings, total cost $0.92; the plugin Stop hooks my machine always runs were present too and all recorded hook_success. Fleet numbers come from parsing every attachment record with a hook_* type in 2,404 session transcripts from the last 30 days, this session and the probe sessions excluded. Exit code and JSON semantics were checked against the hooks reference and CHANGELOG.md fetched the same day; the schema-validation claim there did not reproduce for decision: "approve" on Stop, and I report the probe, not the document. I did not run /goal and did not see the TUI rendering, only the stream and transcript records.