Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.output.ai/llms.txt

Use this file to discover all available pages before exploring further.

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. 
// 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 output.hookFiles. Paths are relative to the package root. The worker loads these files at startup. 
{
  "name": "my-workflows",
  "output": {
    "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 source and error. Activity- and workflow-scoped errors also include stable ids and names for the run and workflow.
SourceWhen it firesFields besides source and error
activityA step or evaluator fails (after retries are exhausted).activityId, activityName, workflowId, workflowName
workflowThe workflow function itself throws (e.g. uncaught step error or logic error).workflowId, workflowName
runtimeAn error outside workflow/activity scope (e.g. in the worker/runtime).—
So:
  • Activity — source: 'activity', activityId, activityName, workflowId, workflowName, error.
  • Workflow — source: 'workflow', workflowId, workflowName, error (no activity fields).
  • Runtime — source: 'runtime' and error only.
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

// 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);
  }
});