How are step errors logged?

main
722c172Dedupe release Slack lines by PR number (#793)
This post might have stale content, as main is 124 commits ahead.

how are step errors logged? i mean if i want to search for a step that failed in my logs

Avatar of anthropic/claude-opus-4.5
Claude Opus 4.5
commented

Now I have a complete picture. Here's how step errors are logged in Vercel Workflow:


##How Step Errors Are Logged

When a step fails, the workflow system logs errors in multiple ways:

###1. Console Logs (Runtime Logs)

Step errors are logged to the console with a specific format. You can search for these patterns in your logs:

For Fatal Errors:

[Workflows] "{workflowRunId}" - Encountered `FatalError` while executing step "{stepName}":
  > {stack trace lines}

Bubbling up error to parent workflow

For Regular Errors (max retries reached):

[Workflows] "{workflowRunId}" - Encountered `Error` while executing step "{stepName}" (attempt {n}, {retries} retries):
  > {stack trace lines}

  Max retries reached
  Bubbling error to parent workflow

For Retryable Errors (still has retries left):

[Workflows] "{workflowRunId}" - Encountered `RetryableError` while executing step "{stepName}" (attempt {n}):
  > {error message}

  This step has failed but will be retried

###2. Event Log (step_failed event)

Each step failure creates a step_failed event that is stored in the world's event log with:

  • correlationId: the step ID
  • eventData.error: the error message
  • eventData.stack: the stack trace
  • eventData.fatal: true if it was a fatal error or max retries reached

###3. OpenTelemetry Attributes

If you have tracing enabled, step failures include these span attributes:

  • step.error.name - Name of the error class
  • step.error.message - The error message
  • step.fatal_error - Boolean indicating if it's fatal
  • step.retry.exhausted - Boolean indicating if all retries were used
  • step.status - Set to "failed"

###Searching Your Logs

To find failed steps in your logs, you can search for:

PatternWhat it finds
[Workflows]All workflow-related logs
step_failedEvent type for failed steps
Encountered \FatalError``Fatal step errors
Max retries reachedSteps that exhausted their retries
will be retriedTransient failures that will retry

The source for this is in packages/core/src/runtime/step-handler.ts (lines ~307-410).


END OF POST

How are step errors logged? — vercel/workflow