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 our "Logs" page, which you'll find in the left hand environment 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

Note: you can also use the debugger to look at test runs as well.

When a workflow runs, each step is executed in sequence. It's important to understand the difference between a step that fails and a step that is skipped, as they have very different effects on the workflow run.

When a channel step encounters an error during execution—such as a template rendering failure or invalid channel configuration—Knock will retry the step up to 3 times. If all retry attempts fail, the entire workflow run is halted and no subsequent steps will execute.

Common causes of channel step failures include:

• Template rendering errors. Invalid Liquid syntax or missing required variables that prevent the template from rendering.
• Invalid channel configuration. Misconfigured channel settings or credentials that prevent the notification from being created.

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.

In contrast to failures, there are several controlled scenarios where a step is skipped and the workflow continues to execute subsequent steps. A skipped step does not generate a message, but it does not halt the workflow.

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 the 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 (e.g., no email address for an email step, no phone number for an SMS step, no channel data for a push step), 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.