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 variable — the default name of the step's configurable Error output variable property, which can be renamed per step — 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.
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.
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 |
External connections call services outside Mosaic. Their responses can represent successful outcomes, warnings, or errors. Custom error mapping and custom branches are independent features: error mapping determines how a response is recorded, while custom branches determine how the journey proceeds.
Each external connection can define conditions that map a service response to a custom error. The mapped error is recorded in the journey's execution events, but mapping it does not create or select a journey branch. For example, you can map an HTTP 400 response to a named error and error code to identify and categorize third-party service issues in journey logs.
Custom branches control the journey path. They do not depend on an error being mapped: you can configure a branch for a success, warning, or error response. You can also configure both features for the same response, for example, map an HTTP 400 response to a custom error and route the journey through an error branch. For more, see External service integration.
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 variable — and sometimes additional error details, depending on the type of error.
Typical fields include:
code— standardized identifierts_error_code— short descriptiondata— optional context
For example:
{
"code": "auth_user_not_found",
"ts_error_code": "User not found",
"data": { "username": "jsmith@example.com" }
}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
errorvariable 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.