title | titleSuffix | description | author | ms.author | ms.service | ms.subservice | ms.custom | ms.topic | ms.date |
---|---|---|---|---|---|---|---|---|---|
Execute a Fail activity in Azure Data Factory and Synapse Analytics |
Azure Data Factory & Azure Synapse |
This article discusses how a Fail activity in Azure Data Factory and Synapse Analytics intentionally throws an error in a pipeline. |
chez-charlie |
chez |
data-factory |
orchestration |
synapse |
conceptual |
09/22/2021 |
You might occasionally want to throw an error in a pipeline intentionally. A Lookup activity might return no matching data, or a Custom activity might finish with an internal error. Whatever the reason might be, now you can use a Fail activity in a pipeline and customize both its error message and error code.
[!INCLUDEappliesto-adf-asa-md]
To use a Fail activity in a pipeline, complete the following steps:
-
Search for Fail in the pipeline Activities pane, and drag a Fail activity to the pipeline canvas.
-
Select the new Fail activity on the canvas if it is not already selected, and its Settings tab, to edit its details.
:::image type="content" source="media/control-flow-fail-activity/fail-activity.png" alt-text="Shows the UI for a Fail activity.":::
-
Enter a failure message and error code. These can be literal string expressions, or any combination of dynamic expressions, functions, system variables, or outputs from other activities.
{
"name": "MyFailActivity",
"type": "Fail",
"typeProperties": {
"errorCode": "500",
"message": "My Custom Error Message"
}
}
Property | Description | Allowed values | Required |
---|---|---|---|
name | The name of the Fail activity. | String | Yes |
type | Must be set to Fail. | String | Yes |
message | The error message that surfaced in the Fail activity. It can be dynamic content that's evaluated at runtime. | String | Yes |
errorCode | The error code that categorizes the error type of the Fail activity. It can be dynamic content that's evaluated at runtime. | String | Yes |
The error message and error code of a Fail activity are ordinarily set by users. To understand the specific meanings of the error codes, contact the pipeline developer. However, in the following edge cases, Azure Data Factory sets the error message and/or error code.
Situation description | Error message | Error code |
---|---|---|
The (dynamic) content in message and errorCode is interpreted correctly. |
The error message that's set by the user | The error code that's set by the user |
The dynamic content in both message and errorCode can't be interpreted. |
"Failed to interpret <activity_name> fail message or error code" | ErrorCodeNotString |
The dynamic content in message can't be interpreted as a string. |
"<activity_name> fail message parameter could not be interpreted as a string" | The error code that's set by the user |
The dynamic content in message resolves to null, an empty string, or white spaces. |
"Failed to interpret <activity_name> fail message or error code" | The error code that's set by the user |
The dynamic content in errorCode can't be interpreted as a string. |
The error message that's set by the user | ErrorCodeNotString |
The dynamic content in errorCode resolves to null, an empty string, or white spaces. |
The error message that's set by the user | ErrorCodeNotString |
The value for message or errorCode that's provided by the user isn't string-able.* |
Pipeline fails with: "Invalid value for property <errorCode /message >" |
|
The message field is missing.* |
"Fail message was not provided" | The error code that's set by the user |
The errorCode field is missing.* |
The error message that's set by the user | ErrorCodeNotString |
* This situation shouldn't occur if the pipeline is developed with the web user interface (UI) of Data Factory.
See other supported control flow activities, including: