Workflows Troubleshooting & FAQs
Learn about common FAQs, tips for debugging, and explanations of error messages to help you quickly identify and resolve workflow issues.
Common errors
The table below outlines common errors that may occur during workflow execution in RiskOS™.
These issues can result from misconfigured steps, invalid variables, or incomplete inputs.
Understanding these patterns can help you debug workflows efficiently, reduce downtime, and implement fallback logic when appropriate.
| Issue | Suggested fix |
|---|---|
Transformation function %s has encountered an error | Verify input parameters, check function syntax and data types, and use INSPECT_VALUE during testing to debug inputs. |
| List X cannot be deleted as it is in use | Remove references from all workflows, including Draft and Published versions. Clear dependencies before deleting. |
| Step received an empty input value | Confirm the variable is populated and spelled correctly. Verify upstream steps generate the expected output. Use INSPECT_VALUE to check. |
| Condition step contains a data type mismatch | Ensure variables use correct data types. Wrap strings in quotes. Debug with INSPECT_VALUE. |
Step %s is not connected to the workflow | Connect all steps properly in the Workflow Builder. |
| Output variable contains invalid characters | Rename the variable using only supported characters. |
| Output variable name is too long | Shorten the variable name to meet platform limits. |
| Tag, scorecard, or decision reference not found | Confirm referenced tags, scorecards, and configuration items exist. |
| Incomplete enrichment step | Assign a valid enrichment provider or API in the step configuration. |
| Condition step is missing a comparison operation | Define both input and output parameters. Ensure all mandatory fields are filled. |
| Decision step is missing a decision value | Select and save a decision outcome. |
| Manual Review step is misconfigured | Assign a valid queue for Manual Review cases. |
| Workflow validation error: variable undefined | Confirm the variable exists, check API payloads include mandatory values, and verify custom variables. Use INSPECT_VALUE to validate inputs. |
Handling step errors in the RiskOS™ Dashboard
RiskOS™ surfaces detailed error descriptions in the Workflow Builder to help you fix issues quickly.
- A summary of errors appears at the top of the canvas.
- Click Saved with Issues to view a list of current errors.
- You can fix issues one by one (saving each correction) or resolve all issues together for efficiency.
Tips for testing and debugging workflows
1. Review the full evaluation input
Check the entire evaluation payload for missing or null fields. Verify data structures haven’t changed.
- You can view and download the raw data from the context menu in Single Case View if you have the correct permissions/
2. Create a copy of the workflow
Always debug on a duplicate workflow to avoid breaking production logic.
3. Use mock data services
Mock services help reduce cost and speed up testing when live data is not needed.
Known issues
- Asynchronous step limitations. Testing is not currently supported for workflows that include asynchronous steps (e.g., OTP, DocV, Wait).
- Caching behavior. Enrichment responses may be cached if the same
eval_idis reused in testing. - Unsupported characters. Special characters in variable names or input fields may cause failures.
- Incomplete configuration. Leaving required fields empty in steps (Condition, Decision, Manual Review) will block workflow execution.
- Environment mismatches. Tags or score cards created in one environment may not exist in another; confirm consistency before deployment.
Working as designed
The behaviors below often look like bugs, but each one is expected. Confirm the behavior here before you change your configuration.
| What you observe | Why it happens |
|---|---|
| A later decision step "never runs" | Only one terminal step runs per evaluation. The event reached an earlier Decision or Decision Rules step on its path and execution stopped there. |
| A Decision Rules rule lower in the list is ignored | Rules are evaluated top to bottom and the first matching rule wins. Reorder so more specific rules sit above broader ones. |
| A scorecard rule did not add to the total | A rule contributes its points only when its condition evaluates to true. Verify the condition with representative test data. |
| Events with no clear outcome fall through | A Decision Rules step with no fallback leaves matching gaps undefined. Always configure the fallback (Else)—either a decision or Continue with next steps without making a Decision. |
| You cannot edit a published or live workflow | Published and live workflows are frozen. Restore to create a new minor version or duplicate to create a new major version, then edit the copy. |
| You cannot make a workflow live | Only one workflow per use case can be live at a time, and you cannot promote a workflow while a Champion–Challenger experiment is active. |
| A change to a live workflow has no effect on traffic | Editing produces a new draft. Traffic continues on the live version until you publish the new version and make it live. |
Note:
Reason codes explain why an outcome was reached. They do not change the decision. For the full list and meanings, see the reason code catalog.
Workflow testing FAQs
How can I fix an error and retest my workflow?
- Draft workflow: Stop the test, update the workflow to resolve the issue, save changes, and restart the test.
- Published workflow: Stop the test, restore the workflow, apply changes, save it, and either test the draft or publish the workflow and test again.
Which IDs can be used for testing?
Use evaluation IDs from your account when selecting historical cases.
IDs are globally unique identifiers, not limited to “applications.”
Is there an API for testing or backtesting?
No. Testing and backtesting can only be initiated via the RiskOS™ Dashboard UI.
There is no API for workflow testing today.
Updated about 1 month ago