chore(kno-11675): Clarify workflow execution behavior#1314
Open
chore(kno-11675): Clarify workflow execution behavior#1314
Conversation
- Add new 'Understanding workflow execution behavior' section to debugging-workflows.mdx explaining: - Channel step failures halt workflow after 3 retry attempts (e.g., template rendering errors, invalid config) - Channel step skips allow workflow to continue (conditions not met, missing config, preference opt-outs, missing recipient data) - Update channel-step.mdx to document step failure behavior during execution - Add warning callout to testing-and-debugging.mdx about template errors halting workflows Resolves KNO-11675 Co-authored-by: Matt Kufchak <matt.kufchak@gmail.com>
|
Cursor Agent can help with this pull request. Just |
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Co-authored-by: Matt Kufchak <matt.kufchak@gmail.com>
cellomatt
changed the title
cellomatt
commented
Feb 13, 2026
Send windows delay notifications but don't cause steps to be skipped. Co-authored-by: Matt Kufchak <matt.kufchak@gmail.com>
cellomatt
changed the title
scoti-knock
reviewed
Feb 20, 2026
| 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: | ||
| 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: |
Contributor
There was a problem hiding this comment.
I think this should technically be left-hand sidebar, but looks like we've used a mix of left hand, left side, and left-hand. I don't have a strong preference and know this came from the original, just noting.
scoti-knock
reviewed
Feb 20, 2026
| <Callout | ||
| type="info" | ||
| title="Note:" | ||
| text="You can use the workflow debugger to inspect any workflow run, regardless of whether it was triggered via the API or the dashboard test runner." |
Contributor
There was a problem hiding this comment.
Suggested change
| text="You can use the workflow debugger to inspect any workflow run, regardless of whether it was triggered via the API or the dashboard test runner." | |
| text="You can use the workflow debugger to inspect any workflow run, whether it was triggered via the API or the dashboard test runner." |
scoti-knock
reviewed
Feb 20, 2026
| - **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](/managing-recipients/setting-channel-data) for a push step), the step is skipped. | ||
| - **A dynamic [batch](/designing-workflows/batch-function), [delay](/designing-workflows/delay-function), or [throttle](/designing-workflows/throttle-function) 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. |
Contributor
There was a problem hiding this comment.
Can we break this into two sentences?
scoti-knock
reviewed
Feb 20, 2026
| - **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. |
Contributor
There was a problem hiding this comment.
I think this would benefit from an image. I can imagine this being hard to follow if you're not already familiar with this
scoti-knock
approved these changes
Feb 20, 2026
Contributor
scoti-knock
left a comment
scoti-knock
left a comment
There was a problem hiding this comment.
Left a few suggestions — things like adding an image could be a follow up ticket IMO.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
This PR clarifies the expected behavior of workflow execution when a step encounters an error versus when it is intentionally skipped.
Previously, the documentation did not explicitly state that a workflow run would halt if a channel step failed after exhausting its retries. This PR addresses KNO-11675 by:
debugging-workflows.mdxexplaining when workflows halt due to channel step failures (e.g., rendering errors) and when steps are merely skipped (e.g., conditions not met, preferences opt-outs).channel-step.mdxto the new debugging documentation.testing-and-debugging.mdxwith a warning about template rendering errors halting workflow execution.These changes provide a clearer understanding of workflow control flow and aid in debugging.
Tasks
KNO-11675
Linear Issue: KNO-11675