# PostToolUseFailure Hook

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

**Field:** Artificial Intelligence  
**Category:** Claude Code  
**Also known as:** PostToolUseFailure

## Think of it like

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

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

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

## Example code

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

Log every failed shell command.

## Why it matters

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

## Common mistake

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

## Three principles

- **When a tool fails.** Not on success.
- **Gets the error.** Name, input, error.
- **Log or hint.** Common uses.

## Related terms

- [PostToolUse Hook](https://learn.benibix.com/term/ai/posttooluse-hook)
- [PreToolUse Hook](https://learn.benibix.com/term/ai/pretooluse-hook)

---

Source: https://learn.benibix.com/term/ai/posttoolusefailure-hook
Author: Behnia Zarei (a developer in Vienna, Austria, who builds and teaches data, AI and business intelligence at BENIBIX)
Publisher: BENIBIX Learn (https://learn.benibix.com/)
Last updated: 2026-11-16
Licence: CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/). Quote freely with attribution.
