# 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

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.

#### Map custom errors

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

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](/guides/orchestration/concepts/external_service_integration#how-it-works).

## 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:

```json
{
  "code": "auth_user_not_found",
  "ts_error_code": "User not found",
  "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](https://portal.transmitsecurity.io/journey-analytics) section of the **Admin Portal**, which lists all journey events — including errors — generated during execution (for more information, see our [Journey analytics](/guides/orchestration/getting-started/journey_analytics) guide).
- For programmatic access, through the [Event Streaming APIs](/openapi/risk/activities.openapi) (for more information, see our [Activities streaming guide](/guides/user/platform/activities_streaming)).


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