Journey errors

To ensure consistent flow logic and traceability, Mosaic Journeys record the outcome of every step as part of the journey execution. Each step’s outcome determines how the journey proceeds and is logged as either a success or failure event, typically carrying an error code and message when applicable.

When a failure occurs, the resulting error data is stored in the error_output variable and logged as part of the journey’s execution events. You can review this data in the Journey Builder to identify and debug issues in the current flow, or in the Journey Analytics section of the Admin Portal, where all journey events — including errors — are logged for review.

This visibility helps you refine your design strategy and build more resilient journeys by understanding how users and systems interact under different conditions.

Logged errors can also support flow logic by serving as triggers for additional actions — for example, using control steps such as Match case to check for a specific error condition and route the flow accordingly.

Error types

Journeys can log different types of errors depending on where the issue occurs and how it affects the flow. The following sections describe each category.

Mosaic-native errors

Errors can be grouped into three categories, defined by their cause and how they are later used.

Error category	Description	Available in logs	Available in journeys	Examples
Flow logic errors	Represent conditions related to the user or flow logic. These are business- or user-flow–driven errors that are meaningful when reviewing or designing a journey.	Yes	Yes — available for debugging and flow logic use	user already exists, session not found
Configuration errors	Represent issues in how a journey or its components were set up, such as a misconfigured external connection or invalid expression.	Yes	Yes — only available for debugging	invalid expression, missing operand, external connection misconfigured
System errors	Represent unexpected or platform-level failures, such as service outages or internal exceptions. These are logged for diagnostics only.	Yes	No	service unavailable, internal exception

Integration-level errors

Mosaic allows you to connect to external services through External Connections. Journeys can then interact with these services either through dedicated integration steps or by using the Invoke Custom HTTP step.

Each External Connection lets you define conditions that trigger custom errors, which are then logged as part of the journey’s execution events. For example, you can map an HTTP 400 response to a named error that appears in the event logs when an external connection returns that response. You can customize both the error name and the error code, helping you identify and categorize third-party service issues directly from the journey logs.

This makes it easier to identify, categorize, and incorporate third-party service errors.

Error structure

When a step fails, Mosaic logs a structured error object as part of the Step_Completed event. Within this event, the additionalParameters field includes data from the error_output variable — and sometimes additional error details, depending on the type of error.

Typical fields include:

code — standardized identifier
ts_error_code — short description
data — optional context

For example:

Copy

Copied

{
  "code": "auth_user_not_found",
  "ts_error_code": "User not found",
  "error_data": { "username": "jsmith@example.com" }
}

Viewing and using error logs

Errors are logged automatically during journey execution and can be reviewed in the following ways:

In the Journey Builder , where you can inspect errors stored in the error_output variable while testing each flow, or reference them as part of the journey logic.
In the Journey analytics section of the Admin Portal , which lists all journey events — including errors — generated during execution (for more information, see our Journey analytics guide).
For programmatic access, through the Event Streaming APIs (for more information, see our Activities streaming guide ).

In all cases, each log event includes a journey_id, step_id, and a timestamp, helping you trace failures and understand their context.