Execute a Fail activity in Azure Data Factory and Synapse Analytics

  • Article

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.

APPLIES TO: Azure Data Factory Azure Synapse Analytics

Create a Fail activity with UI

To use a Fail activity in a pipeline, complete the following steps:

  1. Search for Fail in the pipeline Activities pane, and drag a Fail activity to the pipeline canvas.

  2. Select the new Fail activity on the canvas if it isn't already selected, and its Settings tab, to edit its details.

    Shows the UI for a Fail activity.

  3. Enter a failure message and error code. These values can be literal string expressions, or any combination of dynamic expressions, functions, system variables, or outputs from other activities.

Syntax

{
    "name": "MyFailActivity",
    "type": "Fail",
    "typeProperties": {
        "errorCode": "500",
        "message": "My Custom Error Message"
    }
}

Type properties

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 to be evaluated at runtime. String Yes
errorCode The error code that categorizes the error type of the Fail activity. It can be dynamic content to be evaluated at runtime. String Yes

Understand the Fail activity error code

Pipeline authors ordinarily set the error message and error code of the Fail activity. 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 set by the user The error code 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 couldn't be interpreted as a string" The error code 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 set by the user
The dynamic content in errorCode can't be interpreted as a string. The error message set by the user ErrorCodeNotString
The dynamic content in errorCode resolves to null, an empty string, or white spaces. The error message 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 wasn't provided" The error code set by the user
The errorCode field is missing.* The error message set by the user ErrorCodeNotString

* This situation shouldn't occur if the pipeline is developed with the web user interface (UI) of Data Factory.

Related content

See other supported control flow activities, including: