Skip to main content

Debugging Workflow Executions

Using Orkes Conductor’s visual workflow diagrams, you can quickly inspect and debug workflow executions during development. All viewable workflow executions are listed in Executions > Workflow.

Workflow Executions page

From this introspection dashboard, you can troubleshoot terminal errors and failures during execution.

note

Refer to Handling Failures for information on native failure-handling features that automatically resolve transient failures.

Searching workflow executions​

The workflow execution data can be filtered by the following parameters:

  • Workflow name
  • Workflow ID
  • Correlation ID
  • Idempotency key
  • Status
  • Execution start time range

The free text search box also enables you to search inside workflow input values, workflow output values, workflow variable values, task output values, correlation ID, and reason for incompletion.

Use the * wildcard to conduct partial searches for Workflow name or Free text search. For example, searching test* will display all workflows with names starting "test".

Workflow search with wildcard support

You can switch on SQL format to search the workflow execution data in SQL format. The following syntax is supported:

  • FIELD = VALUE
  • FIELD IN (value1, value2)
  • AND

You can use SQL to search the following:

  • workflowId
  • correlationId
  • workflowType
  • status
  • startTime
  • modifiedTime

Example

Here are some example queries:

  • workflowType = your_workflow_name
  • status IN (PAUSED, RUNNING)
  • startTime >1726655978410
  • startTime < 1696143600000
  • workflowType = your_workflow_name AND status = PAUSED
  • workflowId IN (3434546, 45365767, 20984885) AND workflowType = test_workflow

You can conduct searches via the Search Workflow Executions API (GET /api/workflow/search) as well. To help format your API search query, you can select the ⏷ (down arrow) icon beside Search > Show as Code to get the same search request as an API call.

Show as code option in Workflow Search

Currently, you can get the workflow search query in cURL and JavaScript.

Workflow search data in code

Inspecting a workflow execution​

In Executions > Workflow, select a specific execution to view the details. Here is an example of the execution details:

Sample Workflow Executions page, with the different tab views.

The introspection dashboard consists of the following tabs:

  • Diagram—Visual diagram representation of the workflow’s task sequence and status, with zoom, search, and download functionalities.
  • Task List—List of details for all tasks in the workflow.
  • Timeline—Chronological timeline of task execution duration, with zoom functionality for granularity.
  • Summary—Summary of key workflow details like workflowId, status, version, start/end time, duration, and reason for incompletion.
  • Workflow Input/Output—Display for the workflow inputs and outputs.
  • JSON—The full workflow execution JSON.
  • Variables—Display for the workflow variables (created using the Set Variable task).
  • Task-to-domain—Display for the task-to-domain mappings used in the workflow execution.

Each tab provides details that can help debug workflow issues.

Diagram tab​

The Diagram tab visually represents task statuses in different colors:

  • Green: Successful task
  • Red: Failed task
  • Orange: Task completed with errors

Refer to Workflow and Task Status for more information on the task status.

Different types of errors in a failed workflow

Selecting a task from the diagram opens a right-hand panel showcasing the task details.

Inspecting a task execution​

The task details dashboard consists of the following tabs:

  • Summary—Summary of key task details like task type, status, retry count, duration, worker, reason for incompletion, and more.
  • Input—Display for the task inputs.
  • Output—Display for the task outputs.
  • Logs—Logs for the task (if supplied by the task).
  • JSON—The task execution JSON.
  • Definition—The task definition used at runtime.

Sample Workflow Executions page, with the task tab details.

If the task has been retried multiple times, you can select an attempt from the dropdown bar and view the details for a specific attempt.

Task attempt dropdown selection.

Debugging a failed task execution​

To debug a failed task, you can try inspecting the following areas:

  • Reason for incompletion—Located in the task’s Summary tab, it captures exceptions thrown by the worker or task, like “Failed to invoke HTTP endpoint”.
  • Worker—Located in the task’s Summary tab, it captures the worker instance that polled for the task. This is useful for digging out logs that aren’t captured in Conductor.
  • Task inputs—Verify if the task’s inputs were correctly provided and computed.
  • Task outputs—Verify if the task’s outputs were correctly provided and computed, and compare them with any task inputs that reference these outputs.

Recovering from failures​

Once the issues regarding the workflow failure are resolved, you can retry the failed workflows using the Actions button in the top-right corner of the page.

Workflow Recovery Options

ActionDescription
TerminateChange the workflow status to TERMINATED.
Restart with current definitionsRestart the workflow from the beginning using the same workflow definition that was referenced in the initial execution. This is useful if the workflow definition has changed and the original definition needs to be retained.
Restart with latest definitionsRestart the workflow from the beginning using the latest workflow definition and version. If you’ve changed the definition, you can use this option to rerun the execution with the latest version.
Retry - from failed taskRetry the workflow from its last failed task.
Re-run workflowRun a new workflow execution instance with updated workflow input parameters, idempotency key, correlation ID, and task-to-domain mapping.
Retry - resume subworkflow(Only if the workflow contains a sub-workflow) Retry the parent workflow from the sub-workflow’s last failed task.