Dealing with errors in workflows#

Sometimes it can happen that you're building a nice workflow, but when you try to execute it, it fails. There are many reasons why workflows executions may fail (some more or less mysterious), for example when a node isn't configured correctly or a third-party service that you're trying to connect to isn't working properly.

But don't panic. We will show you some ways in which you can troubleshoot the issue, so you can get your workflow up and running as soon as possible.

Checking failed workflows#

When one of your workflows fails, it's helpful to check the execution log by clicking on Executions in the left-side panel. The executions log shows you a list of the latest execution time, status, mode, and running time of your saved workflows.

To investigate a specific failed execution from the list, click on the name or 'view' button on the row of the respective execution.

This will open the workflow in read-only mode, where you can see the execution of each node. This representation can help you identify at what point the workflow ran into issues.

To toggle between viewing the execution and the editor, click the Editor | Executions button at the top of the page.

Catching erroring workflows#

To catch failed workflows, create a separate Error Workflow with the Error Trigger node, which gets executed if the main execution fails.

Then, you can take further actions by connecting other nodes, for example sending notifications using email or Slack about the failed workflow and its errors. To receive error messages for a failed workflow, you need to select the option Error Workflow in the Workflow Settings of the respective workflow.

The only difference between a regular workflow and an Error Workflow is that the latter contains an Error Trigger node. Make sure to create this node before you set a workflow as Error Workflow.

Error workflows

You don't need to activate workflows that use the Error Workflow node.
A workflow that uses the Error Trigger node uses itself as the error workflow.
The Error Trigger node is designed to get triggered only when the monitored workflow gets executed automatically. This means you can't test this (to see the result of) an error workflow while executing the monitored workflow manually.
You can set the same Error Workflow for multiple workflows.

Exercise#

In the previous chapters, you've built several small workflows. Now, pick one of them that you want to monitor. Create an Error Workflow that sends a message to a communication platform (for example, Slack, Discord, Telegram, or even email) if that workflow fails. Don't forget to set this Error Workflow in the settings of the monitored workflow.

Show me the solution

The workflow for this exercise looks like this:

To check the configuration of the nodes, you can copy-paste the JSON code of the workflow:

{
	"nodes": [
		{
			"parameters": {},
			"name": "Error Trigger",
			"type": "n8n-nodes-base.errorTrigger",
			"typeVersion": 1,
			"position": [
				720,
				-380
			]
		},
		{
			"parameters": {
				"channel": "channelname",
				"text": "=This workflow {{$node[\"Error Trigger\"].json[\"workflow\"][\"name\"]}}failed.\nHave a look at it here: {{$node[\"Error Trigger\"].json[\"execution\"][\"url\"]}}",
				"attachments": [],
				"otherOptions": {}
			},
			"name": "Slack",
			"type": "n8n-nodes-base.slack",
			"position": [
				900,
				-380
			],
			"typeVersion": 1,
			"credentials": {
				"slackApi": {
					"id": "17",
					"name": "slack_credentials"
				}
			}
		}
	],
	"connections": {
		"Error Trigger": {
			"main": [
				[
					{
						"node": "Slack",
						"type": "main",
						"index": 0
					}
				]
			]
		}
	}
}

Throwing exceptions in workflows#

Another way of troubleshooting workflows is to include a Stop and Error node in your workflow. This node throws an error, which can be set to one of two error types: an error message or an error object. The error message returns a custom message about the error, while the error object returns the type of error.

The Stop and Error node can only be added as the last node in a workflow.

When to throw errors

Throwing exceptions with the Stop and Error node is useful for verifying the data (or assumptions about the data) from a node and returning custom error messages.

If you are working with data from a third-party service, you may come across problems such as: wrongly formatted JSON output, data with the wrong type (for example, numeric data that has a non-numeric value), missing values, or errors from remote servers.

Though this kind of invalid data might not cause the workflow to fail right away, it could cause problems later on, and then it can become difficult to track the source error. This is why it's better to throw an error at the time you know there might be a problem.