onFailure
A Claude Code settings key, read out of the shipped bundle. No mined inventory carries it: everything below comes from what this site has written about it.
Claude Code now flags policy helpers that require success but have no fallback settings
Not Anthropic's. This is the line from the earliest changelog entry here that named it, v2.1.265.
In the changelogs
20Releases whose published page names onFailure.
-
v2.1.317
SDK hooks set to block on failure now stop the action
Claude Code now tells SDK programs it honors onFailure on hooks, and a hook set to block keeps waiting for its own host on remote connections
found in this entry's text, named in this entry
-
v2.1.317
SDK hooks can now block when they fail with
onFailureSDK hook callbacks take an
onFailureoption:continueby default, orblockto treat a failed callback as a blockfound in this entry's text, named in this entry
-
v2.1.317
Agent SDK hook callbacks can now be set to stop work when they fail
In block mode, a failed SDK hook callback now raises an error instead of being quietly ignored
named in this entry
-
v2.1.317
SDK hosts can choose whether a failing hook lets work continue
Hook matchers set by an SDK host accept onFailure as "continue" or "block"; any other value is treated as "block" with a warning
found in this entry's text, named in this entry
-
v2.1.317
SDK holds your prompt until hooks set to block on failure are confirmed
In the SDK, a hook set to onFailure "block" now holds the prompt until Claude Code confirms it will honour that setting, and errors if it cannot
found in this entry's text, named in this entry
-
v2.1.317
Plain output from some background hooks can now become start-of-session context
Some background hooks that print plain text and succeed now have that text passed to Claude as context when a session starts
found in this entry's text
-
v2.1.317
Callback hooks can now block an action when they fail
Callback hooks set with
onFailuretoblocknow block when they fail, as HTTP hooks already didfound in this entry's text, named in this entry
-
v2.1.311
Hook fingerprinting no longer skips hooks that are not command hooks
A step that builds an identifying fingerprint for each hook no longer skips every hook whose type is not command
found in this entry's text
-
v2.1.310
Changes to PowerShell hook handling and a check for signed answers
Claude Code now picks out certain blocking PowerShell hooks and can check whether an answer carries a valid digital signature
found in this entry's text
-
v2.1.309
Hook messages give specific fixes when Git Bash is missing
When a hook blocks because Git Bash wasn't found, the message now gives PowerShell hooks and other hooks their own fix
found in this entry's text
-
v2.1.300
Changes to how organisation-managed hooks combine with other hooks
Hook selection for organisation-managed setups now includes policy hooks delivered by plugins, and hooks that continue on failure can be marked contested
found in this entry's text
-
v2.1.299
Hooks that look written for bash can now be flagged on PowerShell setups
On a machine whose default shell is PowerShell, a command hook that isn't set up for PowerShell can now be flagged with a "noBash" reason
found in this entry's text
-
v2.1.299
Unfinished PreToolUse hooks now respect onFailure: continue
A
PreToolUsehook withonFailure: continuethat does not finish lets the call run; otherwise the call is blocked with advicefound in this entry's text, named in this entry
-
v2.1.296
Cloud hooks now track their failure setting unless it is "block"
Cloud hook comparisons now take
onFailureinto account unless it is "block", and headless launches report how many built-in tools they havefound in this entry's text, named in this entry
-
v2.1.295
A new setting limits what your own skills, agents and hooks can do
Setting CLAUDE_CODE_RESTRICT_PERSONAL_CONFIG stops your own skills, agents and hooks from widening permissions, and makes key hooks required
found in this entry's text
-
v2.1.295
Hooks can be set to block when they fail
Command and http hooks accept a new onFailure field, and setting it to "block" makes a failing hook block the action
found in this entry's text, named in this entry
-
v2.1.295
HTTP hooks accept an onFailure setting, and more web files get proper extensions
HTTP hooks gain an onFailure setting, and icons, stylesheets, scripts, fonts and similar files now get their own file extensions
found in this entry's text, named in this entry
-
v2.1.265
policyHelpers per-entry onFailure and retries settings now validated for effect
Claude Code now flags policy helpers that require success but have no fallback settings
found in this entry's text, named in this entry
-
v2.1.265
policyHelper singular field now also warns for ignored onFailure/retries
Claude Code now warns if onFailure or retries is set on the singular policyHelper entry, since those are ignored there
found in this entry's text
-
v2.1.265
policyHelpers
onFailure/retriesper-OS validation messages addedClaude Code now warns when
onFailureorretriesare set on the wrongpolicyHelperkey, and can refuse to start if an OS-admin helper failsfound in this entry's text, named in this entry
First cited
6The earliest release whose published evidence quoted onFailure was v2.1.265, 8 Sep 2026. That is the oldest release this project wrote about it, so it is a floor on the name's age and not the release that introduced it. It is not a presence reading: which builds carried the name is the table below.
Presence across releases
0The miner has never read a build containing this name. It is here because a changelog entry of ours names it, which is evidence that it existed and not evidence of which releases carried it. The inventory starts at v2.1.138 and everything older than that was never mined.
Read out of the published npm bundle release by release, and out of Anthropic's own documentation as this site captured it. Nothing on this page is a description anybody here wrote about what the settings key does. All settings keys.