---
title: "Error Hooks"
description: "Observe workflow, activity, and runtime errors without affecting execution"
---

Error hooks let you run code whenever a workflow, activity (step/evaluator), or runtime error occurs. Use them for logging, metrics, or alerting. When an error is emitted, all registered handlers are triggered at the same time (concurrently). Handler code is invoked asynchronously and never throws — any error in your handler is caught and logged by the framework.

## Setup

### 1. Create a hook file

Create a file that registers your handler. Import `onError` from `@outputai/core/hooks`.

```javascript
// src/error_hooks.js
import { onError } from '@outputai/core/hooks';

onError(async (payload) => {
  console.log('Error', payload);
});
```

### 2. Register the file in package.json

List your hook file(s) under `outputai.hookFiles`. Paths are relative to the package root. The worker loads these files at startup.

```json
{
  "name": "my-workflows",
  "outputai": {
    "hookFiles": ["./src/error_hooks.js"]
  }
}
```

You can register multiple files: `"hookFiles": ["./src/error_hooks.js", "./src/other_hooks.js"]`.

## The three sources

Errors are emitted from three origins. Every payload includes `eventId`, `source`, and `error`. Activity- and workflow-scoped errors also include stable ids and names for the run and workflow.

| Source | When it fires | Fields besides `eventId`, `source`, and `error` |
|--------|----------------|----------------------------------------|
| `activity` | A step or evaluator fails (after retries are exhausted). | `activityId`, `activityName`, `workflowId`, `workflowName` |
| `workflow` | The workflow function itself throws (e.g. uncaught step error or logic error). | `workflowId`, `workflowName` |
| `runtime` | An error outside workflow/activity scope (e.g. in the worker/runtime). | — |

So:

- **Activity** — `eventId`, `source: 'activity'`, `activityId`, `activityName`, `workflowId`, `workflowName`, `error`.
- **Workflow** — `eventId`, `source: 'workflow'`, `workflowId`, `workflowName`, `error` (no activity fields).
- **Runtime** — `eventId`, `source: 'runtime'`, and `error` only.

`eventId` is a UUID v4 stamped per emit — use it as a stable idempotency key when forwarding errors to external systems (Sentry, PagerDuty, your own incident pipeline). Use `source` to branch in one handler, or ignore payload fields that are undefined for that source.

## Handler safety: no throws

Your handler is wrapped in a try/catch. If the handler throws or rejects, the framework catches it, logs it (e.g. `onError hook error` with the error), and does not rethrow. Execution of the workflow and worker continues. You can focus on side effects (logging, metrics, alerts) without worrying about breaking the run.

## Example

```javascript
// src/error_hooks.js
import { onError } from '@outputai/core/hooks';

onError(async (payload) => {
  const { source, error } = payload;
  if (source === 'activity') {
    const { workflowName, activityName, workflowId, activityId } = payload;
    console.error(
      `Step/evaluator failed: ${workflowName} (${workflowId}) / ${activityName} (${activityId})`,
      error
    );
  } else if (source === 'workflow') {
    const { workflowName, workflowId } = payload;
    console.error(`Workflow failed: ${workflowName} (${workflowId})`, error);
  } else {
    console.error('Runtime error', error);
  }
});
```
