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 under Observability > Runs in the dashboard sidebar, which lists every workflow run in the current environment. Filter that list if desired, then select a run to open it in the debugger.

Finally, you can reach the debugger under Observability > API logs in the dashboard sidebar. 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 why. This can help you understand why a recipient did not receive a notification on a particular channel, or why 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.

A batch step aggregates many workflow runs into a single notification. The first trigger for a recipient opens the batch window. Every trigger that arrives while that window is open is added to the batch as an activity, and its own workflow run terminates at the batch step. When the window closes, the run that opened the batch continues to the next step.

This means that a workflow with a batch step produces two types of runs:

• Runs that open a batch. These runs pause at the batch step, then resume and execute the remaining steps when the window closes. Look here for any messages that were generated after the batch closed, along with any errors.
• Runs that join a batch. These runs terminate at the batch step. Steps after the batch step show "Will not execute" with the log "This workflow run was added to the batch function of a pre-existing workflow run." See the instructions below for finding the run that opened the batch and any messages that it generated after the batch window closed.

The batch step is what links runs together, and the workflow debugger surfaces that link in both directions.

Open any workflow run and select the batch step in the debugger. What you see depends on which type of run you selected:

Label	Application	Description
Batched by	Shown on a run that joined an open batch	Displays a link to the workflow run that started the batch. That run is where the rest of the workflow executes after the batch window closes.
Batch closes at	Shown on a run that opened a batch, while its window is still open	Displays a timestamp indicating when the batch window will close. The run remains in a Paused status until the window closes. Subsequent runs that are added to the batch will not be listed here until the window closes and the batch is finalized.
Batched workflow runs	Shown on a run that opened a batch, after its window has closed	Displays a list of up to ten of the runs collected into the batch, followed by the total number of runs in the batch (including the run that opened the batch; for example, "Showing 4 of 5 total batched workflow runs"). Follow any link to open a batched run in the debugger.

When a batch step is configured to immediately flush its leading item, the run that opens the batch continues past the batch step right away and is not included in the final batch. Additional batched triggers are aggregated on the second run added to the batch, so that is the run where you will find the batched workflow runs list and any messages that the batch generated.