Troubleshooting Workflow Errors

Derick Larson


Task errors are defined in their own portion of the Activity console. They are always displayed in the order they are recorded with the most recent first. Each error is assigned an integer as an Id. Error console generic

Even though they have their own console, errors are normally referenced from a task in a Run. error in task run

From the Dretails section you can click on the Error # and go directly to the error.

In the sections below we'll describe how to read, and troubleshoot various workflow errors.

Reading a Task Error

Each error is displayed in the same console format: task error expanded details

Along the top of the console is the Error Id and information about the original run (including a link to the tree).

Below that are tabs for the Details (default) and the Resolution (covered later). And on the right side is a button to open the Builder. If you chose to open the builder and the error is based on a node, that node will be highlighted and placed in the middle of the screen.

The section in blue is for resolving errors and recording actions taken. It is covered in a section below.

The Details section contains any specific information about the error from the the Task engine. Normally, this is a stack trace.

In most cases, the details section includes a short sentence describing the error, a short Problem declaration, and then the entire Stack Trace. error details

Connector Errors

Connector errors are similar, but include a little more information around the two nodes that are the start and end of the connectors.

connector error details

Common Task Errors

In the next sections are some common task errors and potential fixes. The desire is to give you some ideas for troubleshooting. So much in Kinetic workflows is personalized to the customer that it is often impossible to give exact solutions.

Unable to retrieve hash value for the key

You can see this error in the connector error description above. It indicates that a reference to a node name is missing, incorrect, or hasn't been executed yet.

For example, in the connector error, ApprovalValue has either not been returned yet, or is incorrectly identified.


This error indicates that within either the handler code, or code in a node parameter, a method was called, but no value was provided.

For example in your handler you have the following code to convert a string variable to an integer x.to_i. If x is nil (null for ruby), you will get the nil:NilClass.

The stack trace will often show a line number in the init.rb file that relates to this error.

Invalid Trigger

This error happens when a trigger tries to complete a deferred node that has already been completed.

Normally this is a breakdown in the logic or process that's creating a trigger. It is either happening at the wrong time, or duplicating a trigger it shouldn't. invalid trigger error

Because you cannot retry the trigger in this case, the Resolve Error section only allows you to enter notes (required).

Resolving Errors

The task engine provides a built-in mechanism for retrying errors in the Resolve Errors section of the error task. In any case where you are able to resolve an error, there is an Additional Actions drop-down with three choices, and a Notes field to record any extra notes (normally for either auditing or future troubleshooting purposes).

resolve errors options

  • Do Nothing. Completes the node and moves on to the next (if allowed by any connector qualifications). This could cause issues farther down the tree if other nodes are expecting to use results from this node. Potential "unable to retrieve Hash Value" errors
  • Retry Task. Assumes that some external changes were made to allow the node to complete poroperly. If the node errors again, another error trigger and error task are created and visible both in the Run and the Errors console.
  • Skip Task. Moves on to the next node (if allowed by any connector qualifications). The node with the error is not completed. As above, there could be issues with other nodes in the tree.

Updating Inputs and Results

It may be necessary, after fixing data that caused an error, to also update where that data appears in inputs or results in the workflow run. There are a couple of places on the Run where you can edit the data yourself and then use the Retry Task option to resolve an error.


Inputs are available at the top of every Run. If you know that an input values is incorrect or invalid (for example an answer is blank or not what is expected), you can update the inputs and either retry or run the tree again. Be careful re-running the tree, you could duplicate messages or other actions created by the tree. run input modify

Make use of the audit message to explain any edits of the input data.


Each node that generates Results has the ability to edit those results. Example of a Task Result: edit task results dialog Task does not allow you to makeup a new Result value, so you are limited to the results defined in the task.

Here is an example from a Routine: routine deferred results modify In this case I selected to audit the deferred results.

Changing the results here will only have an effect on any Task that runs after the change. Completed tasks are not updated.

The Ability to Retry Errors

The platform allows retries of errors that will consistently have the desired behavior after being retried. For example, we know that if a handler raises an exception that the tree has not done any downstream processing and the node can safely be retried. In other cases, such as a malformed tree, it is impossible to know the expected vs actual outcome so the platform can't effectively allow retries.

Errors that can be retried:

  • Connector Errors (Continue or Cancel)
  • Handler Errors (Retry or Skip)
  • Node Parameter Errors (Retry or Skip)
  • Missing Handler Errors (Retry or Skip)
  • Missing Routine Errors (Retry or Skip)
  • Source Errors (Retry)

Errors that can not be retried:

  • Invalid Trigger Error (these are raised for things like attempting to update/complete a closed task node)
  • Node Message Error (these are raised for invalid node messages)
  • Tree Error (these are raised for invalid trees)
  • System Error, Unidentified Error, Unknown Variable Error (these are unexpected errors and likely should be reported to support)