Error Handling

When something throws in your workflow, Output handles it differently depending on where it happens. Steps and evaluators are retried automatically. In workflow code, only explicit fatal failures end the run immediately — other throws retry the Workflow Task. You can control this with retry options, non-retryable errors, and try/catch.

How interceptors classify errors

Output’s workflow and activity interceptors decide whether a failure ends the execution, retries, or is rethrown as Temporal already classified it.

Workflow

Error	Behavior
`ContinueAsNew`	Ends the trace as continued-as-new and rethrows
Cancellation (`isCancellation`)	Sinks a serialized error (without `stack`) and rethrows
`FatalError` / `ValidationError` / `TransparentFatalError`	Unwraps `TransparentFatalError` to its cause, sinks the serialized error, and throws a non-retryable `ApplicationFailure` with the serialized error in `.details[0].error` — the workflow fails
Temporal failures (`ActivityFailure`, `ChildWorkflowFailure`, other `TemporalFailure`)	Sinks the serialized error and rethrows unchanged. (`CancelledFailure` usually matches `isCancellation` first.)
Other errors (`TypeError`, bad `JSON.parse`, unexpected throws)	Rethrown unchanged without sinking — the Workflow Task retries (or stays open until timeout). The CLI can look “stuck” until the task succeeds, times out, or you throw `FatalError` / an `ApplicationFailure`

Activity (steps and evaluators)

Error	Behavior
`CompleteAsyncError`	Recorded as an async handoff in the trace (not an error). No activity error hook. Rethrown
Temporal failures (`TemporalFailure`)	Activity error hook and trace error fire, then rethrown unchanged
`FatalError` / `ValidationError` / `TransparentFatalError`	Activity error hook and trace error fire (using the unwrapped cause for `TransparentFatalError`), then converted to `ApplicationFailure` with serialized error in `.details[0].error`. Always `nonRetryable: true`. User `nonRetryableErrorTypes` cannot make these retryable
Other errors	Activity error hook and trace error fire, then converted to `ApplicationFailure` with serialized error in `.details[0].error`. `nonRetryable` when the error class name is listed in the activity retry policy’s `nonRetryableErrorTypes`

ValidationError and TransparentFatalError both extend FatalError, so they share the fatal rows above. TransparentFatalError is only a transport: interceptors use its .cause for logs, traces, hooks, and failure details. See FatalError, ValidationError, and TransparentFatalError for when to throw each.

Steps and Evaluators

When a step or evaluator throws, we retry it automatically with exponential backoff. After all retries are exhausted, the error propagates to the workflow (typically as an ActivityFailure cause chain). Default retry behavior:

Setting	Default
`initialInterval`	10s
`backoffCoefficient`	2.0
`maximumAttempts`	3
`nonRetryableErrorTypes`	`['FatalError']`

This means a failing step waits 10s, then 20s, then fails for good. You can override these per step via the options.activityOptions property — see Step Options. Custom nonRetryableErrorTypes are added alongside FatalError; Output always keeps FatalError non-retryable.

Workflows

Errors in the workflow fn itself are classified as in the table above. Throw FatalError or ValidationError when the run must fail immediately. Ordinary bugs (for example a bad JSON.parse) retry the Workflow Task instead of failing the execution right away. You can catch step errors with try/catch and handle them however you want:

workflow.ts

import { workflow } from '@outputai/core';
import { lookupCompany, generateSummary } from './steps.js';
import { EnrichmentInput, EnrichmentOutput } from './types.js';

export default workflow({
  name: 'lead_enrichment',
  inputSchema: EnrichmentInput,
  outputSchema: EnrichmentOutput,
  fn: async (input) => {
    const company = await lookupCompany(input.companyDomain);

    let summary;
    try {
      summary = await generateSummary(company);
    } catch (error) {
      // Step failed after all retries — use a fallback
      summary = `${company.name} is a company in the ${company.industry} industry.`;
    }

    return { company: company.name, summary };
  }
});

// types.ts
// import { z } from '@outputai/core';
//
// export const EnrichmentInput = z.object({
//   companyDomain: z.string()
// });
//
// export const EnrichmentOutput = z.object({
//   company: z.string(),
//   summary: z.string()
// });

If you don’t catch a step failure, it surfaces to the workflow as a Temporal failure and the workflow fails (unless you handle it).

Checking error types in workflows

Errors thrown by steps and evaluators cross Temporal’s Activity boundary before they reach workflow code. Temporal serializes them into a failure cause chain, so a direct error instanceof CustomError check is not reliable inside a workflow. The same applies when Output wraps a failure in ApplicationFailure or TransparentFatalError — the error you care about is often on .cause, not the outer object. Use hasErrorType(error, CustomError) from @outputai/core to walk the complete cause chain. It matches native instances as well as Temporal’s serialized type and name fields. Define the custom error in a shared module imported by both the step and workflow:

types.ts

export class CompanyNotFoundError extends Error {}

steps.ts

import { step } from '@outputai/core';
import { CompanyNotFoundError } from './types.js';

export const lookupCompany = step({
  name: 'lookup_company',
  fn: async () => {
    throw new CompanyNotFoundError('Company not found');
  }
});

workflow.ts

import { hasErrorType, workflow } from '@outputai/core';
import { lookupCompany } from './steps.js';
import { CompanyNotFoundError } from './types.js';

export default workflow({
  name: 'company_lookup',
  fn: async () => {
    try {
      return await lookupCompany();
    } catch (error) {
      if (hasErrorType(error, CompanyNotFoundError)) {
        return null;
      }

      // Preserve unexpected failures.
      throw error;
    }
  }
});

Always rethrow errors that do not match the type the workflow explicitly handles.

Error metadata

Trace destinations are stored in Temporal memo and exposed as the workflow result’s trace field. They are available independently of whether the workflow succeeds or fails. Current API responses expose failures as a serialized error object with name, message, and any additional diagnostic properties captured from the original error. Activity failures also include activityType when available. If you inspect Temporal errors directly, workflow failures remain native Temporal errors such as ApplicationFailure or ChildWorkflowFailure. Output may store the serialized original error under details[0].error on a nested failure in the .cause chain.

function getSerializedWorkflowError(error: unknown) {
  let current = error as { cause?: unknown; details?: unknown[] } | null;

  while (current) {
    const detail = current.details?.find((value) =>
      value &&
      typeof value === 'object' &&
      'error' in value
    );

    if (detail && typeof detail === 'object' && 'error' in detail) {
      return detail.error;
    }

    current = current.cause as typeof current;
  }

  return null;
}

FatalError, ValidationError, and TransparentFatalError

Sometimes retrying won’t help — the API key is invalid, the resource doesn’t exist, or the data is fundamentally wrong. For these cases, throw FatalError or ValidationError to fail immediately without retries. ValidationError and TransparentFatalError extend FatalError. The entire FatalError family is always non-retryable and cannot be made retryable through activity options. Throw a regular or custom Error when retry configuration should control the behavior.

Error	Use when
`FatalError`	The failure is not recoverable. Retrying would not help (e.g. invalid API key, resource not found, business rule violation).
`ValidationError`	The data is invalid. Use for custom validation checks alongside the framework’s built-in schema validation.
`TransparentFatalError`	An existing error must be non-retryable, but its original type, message, cause chain, and diagnostic properties should remain visible.

All three are exported from @outputai/core:

steps.ts

import { step, FatalError, ValidationError } from '@outputai/core';
import { getContact } from '../../clients/hubspot.js';
import { LookupContactInput, LookupContactOutput } from './types.js';

export const lookupContact = step({
  name: 'lookupContact',
  description: 'Look up a contact in HubSpot',
  inputSchema: LookupContactInput,
  outputSchema: LookupContactOutput,
  fn: async (email) => {
    const contact = await getContact(email);

    if (contact.error === 'INVALID_API_KEY') {
      // Don't retry — the key won't fix itself
      throw new FatalError('HubSpot API key is invalid');
    }

    if (!contact.properties?.email) {
      // Data doesn't match what we need
      throw new ValidationError('Contact has no email address');
    }

    return {
      exists: true,
      contactId: contact.id,
      lifecycleStage: contact.properties.lifecyclestage
    };
  }
});

TransparentFatalError accepts an existing Error as its cause. It has the same non-retryable behavior as FatalError, but Output removes the wrapper when reporting or propagating the failure. Logs, traces, hooks, and workflow results therefore show the original error rather than a generic fatal-error message.

import { TransparentFatalError } from '@outputai/core';

try {
  await callProvider();
} catch (error) {
  if (error instanceof ProviderError && !error.isRetryable) {
    throw new TransparentFatalError(error);
  }
  throw error;
}

Schema Validation

The framework validates inputs and outputs automatically using your Zod schemas. When validation fails, it throws a ValidationError with a message that tells you exactly what went wrong. Steps and evaluators: Input is validated against inputSchema before fn runs. The return value is validated against outputSchema after fn returns. If either fails, the step fails immediately (no retries). Workflows: Input is validated against inputSchema before the workflow starts. Output is validated against outputSchema after the workflow returns. If either fails, the execution fails. The error message includes context like "Step lookupContact input validation failed: ..." so you can trace exactly where and why validation failed.

Start Here

Workflows

Steps

Prompts

Clients

Costs

Evaluators

Production Readiness

Deployment

Integrate with Your App

Packages

Releases

How interceptors classify errors

Workflow

Activity (steps and evaluators)

Steps and Evaluators

Workflows

Checking error types in workflows

Error metadata

FatalError, ValidationError, and TransparentFatalError

Schema Validation

​How interceptors classify errors

​Workflow

​Activity (steps and evaluators)

​Steps and Evaluators

​Workflows

​Checking error types in workflows

​Error metadata

​FatalError, ValidationError, and TransparentFatalError

​Schema Validation

How interceptors classify errors

Workflow

Activity (steps and evaluators)

Steps and Evaluators

Workflows

Checking error types in workflows

Error metadata

FatalError, ValidationError, and TransparentFatalError

Schema Validation