Debugging workflows

Sometimes you'll encounter issues with a workflow run that require more visibility into the Knock engine. Knock comes pre-built with a powerful workflow debugger that you can use to understand the state of individual workflow runs.

Using the workflow debugger, you can answer questions such as:

• What messages did this workflow run generate?
• Why did this step not produce any messages?
• Did this recipient have preferences set that opted them out from receiving a notification?
• What prevented this step from executing?

You can see a video of our workflow debugger in action here:

You can access the workflow debugger from the "Runs" tab on a given workflow or the "Workflow runs" tab on a recipient record.

You can also access it from our "Logs" page, which you'll find in the left hand sidebar in the dashboard. From there:

1. Find an API log that triggered a workflow run (hint: you can use the filters to find only workflow API requests)
2. In the right hand panel, click the "Workflow runs" tab
3. Select a workflow run for any recipient to view the debugger

When a workflow runs, each step is executed in sequence. Sometimes an individual step is skipped or encounters an error, and it's important to understand how this affects the workflow run as a whole.

There are several controlled scenarios where a step is skipped and the workflow run continues to execute subsequent steps.

Steps are skipped when:

• Step conditions are not met. If a step has conditions configured and they evaluate to false, the step is skipped.
• Channel configuration is missing. If the channel associated with a step has not been configured in the current environment, the step is skipped.
• Recipient preferences opt out. If the recipient has set preferences that opt them out of this notification type or channel, the step is skipped.
• Recipient is missing required data. If the recipient lacks the data required for delivery on this channel (for example, no email address for an email step, or no channel data for a push step), the step is skipped.
• A dynamic batch, delay, or throttle step encounters an invalid window value. If a workflow step encounters a missing or invalid dynamic window value (like a timestamp in the past), the step is skipped.

The workflow debugger will indicate when a step has been skipped and provide the reason, helping you understand why a recipient did not receive a notification on a particular channel or a workflow function was not processed as expected.

When a workflow step encounters an error during execution (such as a template rendering error or an error response from a fetch step), Knock will retry the step up to 3 total times. If all retry attempts fail, the step is marked as failed and the workflow run is halted. No subsequent steps will execute.

Common causes of workflow step failures include:

• Template rendering errors. Invalid Liquid syntax or missing required variables that prevent the message template from rendering.
• Fetch step errors. Errors or timeouts from the HTTP request made by the fetch step.

You can identify failed steps in the workflow debugger by looking for error states on individual steps. The debugger will show you the error details to help diagnose and fix the issue.