Skip to content
BENIBIX Learn

PostToolUseFailure Hook

AI⌨️ Claude CodeConfiguration

Also known as PostToolUseFailure

The event when a tool fails, used to log, alert or give Claude a hint.

Think of it like

It is like an alarm. It rings only when a job goes wrong.

Example

Jack's tests keep failing on a missing package. His hook spots that error and tells Claude to run npm install first.

Why it matters

Success and failure come through different doors. A hook on success never sees a failure.

Definition

PostToolUseFailure is the hook event that fires when a tool starts but fails. For example, a command errors out or an MCP tool returns an error. The hook gets the tool name, its input and the error. Use it to log failures, send an alert, or give Claude a hint about what to try next.

Example code

json
{
  "hooks": {
    "PostToolUseFailure": [
      { "matcher": "Bash", "hooks": [{ "type": "command", "command": "./log-failure.sh" }] }
    ]
  }
}
Log every failed shell command.

Common mistake

Putting a check only on PostToolUse and wondering why it misses errors. Add it here too.

Key takeaways

  1. 1
    When a tool fails. Not on success.
  2. 2
    Gets the error. Name, input, error.
  3. 3
    Log or hint. Common uses.