Updated September 27, 2026

Workflow Doctor: Diagnose and Fix a Workflow

Applies to: All editions · Web app and Desktop app · Permission to edit workflows

Overview

A workflow is the one test in Shift-Left Studio that you assemble by hand: blocks on a canvas, green connectors for the order of execution, and data connectors that carry values from one step to the next. When something is wrong with that wiring, the symptoms are rarely obvious. A workflow may refuse to save, or it may save, run, and fail against the real API for a reason that has nothing to do with the API.

The Workflow Doctor reads your workflow and tells you what is actually wrong with it, in plain words, and offers the change that fixes each problem where a safe fix exists. It reads the workflow four ways: its structure, the data each step needs, what its past runs showed, and the requirement it was built from.

The Doctor checks what is on your canvas right now, including edits you have not saved yet. A fix it makes appears on the canvas in front of you, and you still decide whether to save it.

Key concepts

Term	Meaning
Finding	One problem the Doctor found, with a title, a short explanation, the evidence behind it, and (when possible) a fix button.
Stops it saving or running	The editor will refuse to save the workflow, or a run cannot start. Fix these first.
Will make it fail	The workflow saves and runs, but it will fail for a reason that is not the API's fault — for example, a step is missing a value it needs.
Worth knowing	Advisory. Not wrong, but worth a look.
Execution connector	The green line that sets the order steps run in.
Data connector	A line that carries a value (such as an order ID) from an earlier step's response into a later step's request.
Extraction	The setting on a step's test that pulls a value out of its response so later steps can use it.
Add-only fix	Every fix the Doctor offers adds something. It never deletes or rewires anything you built.

Before you begin

Open a workflow in the flow editor from Workflows in the top navigation.
Save the workflow at least once. The Check workflow button does not appear on a workflow that has never been saved, because there is nothing yet for the Doctor to compare against.
To use the run-based checks, the workflow should have run at least once. Without a run, the Doctor still checks structure and data, and says that nothing has been observed yet.
To ask questions about the workflow in the Doctor panel, the project assistant must be available in your installation (an AI provider must be configured).

Step 1 — Open the Doctor

You can open the Doctor in two ways.

From the editor header

Open the workflow in the flow editor.
Click Check workflow in the header, next to Launch Workflow and Save.

From the save check

Click Save. If the workflow is not connected correctly, the Flow Validation Required dialog appears.
Click Check and fix. Instead of a generic list of instructions, the Doctor tells you which of them applies to this workflow and offers to connect it for you.

The Check this workflow panel opens on the right. While it reads, it shows Reading the flow, the steps and the runs…, then a one-line summary.

Note: The Doctor reads the canvas at the moment you open it. If you make more changes while the panel is open, click Check again (the circular arrow at the top of the panel) to re-read.

Step 2 — Read the findings

Findings are grouped by severity, worst first: Stops it saving or running, Will make it fail, and Worth knowing. Each group shows a count.

For each finding:

Read the title. It names the blocks involved, for example "Get order" needs orderId and is not given one.
Click the title to select those blocks on the canvas, so you can see exactly where the problem is.
Read the evidence lines under the explanation, when present. They show what the Doctor based its finding on.
Click Why this matters to see why the problem affects your run. Click Hide why this matters to collapse it.

When the Doctor finds nothing, the panel shows a green confirmation instead of a list.

What the Doctor reads

Reading	What it checks
Structure	Is there exactly one Start block and at least one Stop (or Skip / Inconclusive) block? Is every block reachable from Start and able to reach an end? Is every line on the canvas a real connector? Does any output have two outgoing connectors? Does every test block have a test, and does that test still exist?
Data bindings	Does each step receive every required input (from the specification's required fields and any placeholders left in the path)? Does each data connector carry a value its source step actually produces? Does a value come from a step that runs earlier, not later? Is every `{{variable}}` set by some step or by the project's environment variables?
Runs	Has the workflow ever run? Has a step failed on every run? Did a step receive nothing where it expected a value on the last run?
Source requirement	If the workflow was built from a requirement, does it still include every step the requirement describes? Does anything check more than status codes?

Tip: A value is only "available" to a step if it comes from a step before it on the execution path. A value produced somewhere else in the workflow, or by a step that runs later, does not count.

Step 3 — Apply a fix

When a safe fix exists, the finding shows a blue button that says exactly what it will do, for example Add a Start block and connect it to "Create order" or Make it a green execution connector.

Click the fix button.
Watch the canvas. The change appears immediately — a new block, a new connector, or handles added to a line.
The finding changes to Done — save to keep it.
The Doctor checks the workflow again automatically, because one fix often resolves another (for example, a connector that also gives a block its route to Stop).
Click Save in the editor header to keep the changes. You can still undo anything the Doctor added before you save.

If a finding has already been fixed by the time you click (for example, you drew the connector yourself), the card says Already sorted.

Fixes that land on the canvas and fixes that write to a test

Most fixes change only the canvas and wait for you to save. One kind is different.

A data fix has two halves that only work together: the connector that carries the value, and the extraction on the earlier step's test that makes the value exist. The extraction lives on the test itself, not on the canvas, so the Doctor saves it to that test immediately when you click the fix. The button tells you this before you click it, for example Have "Create order" extract id, and feed it into this step, and the confirmation afterwards says which it was:

Confirmation	What happened
Done — "orderId" is now extracted by the earlier step	The Doctor added a new extraction to the earlier step's test.
Done — that step already extracted it	The extraction already existed; only the connector was added.
Done — "orderId" was being read from a path that could never resolve; the earlier step now reads it correctly	The step named the value, but read it from a path such as `data[*].id`, which describes the shape of a response rather than a location in it. The Doctor corrected the path.

The connector half still needs you to click Save.

Common findings and their fixes

Finding	Severity	Fix offered
This workflow has no Start block	Stops it saving or running	Add a Start block and connect it to the first step
This workflow has no Stop block	Stops it saving or running	Add a Stop block after the last step
The line from "A" to "B" is not a connector	Stops it saving or running	Make it a green execution connector
"Step" never runs	Stops it saving or running	Connect an earlier block to it
A block cannot reach an end	Stops it saving or running	Connect it to a Stop block
"Step" needs a value and is not given one	Will make it fail	Have an earlier step extract the value and feed it in
"Step" does not produce a value a connector expects	Will make it fail	Have that step extract it from its response
"Step" uses `{{token}}`, which nothing sets	Will make it fail	Feed the value from an earlier step, when one produces it
"Step" received no value on the last run	Will make it fail	Rewire the binding that failed in practice

Note: "The line is not a connector" is worth special attention. The line is drawn on the canvas, so the workflow looks connected, but it has no handles, so neither the save check nor a run follows it.

Step 4 — Handle findings the Doctor will not fix

Some findings have no fix button. Instead they show Not something I should change: followed by the reason. This is deliberate: in each case, the change would be a decision about what your workflow is for, or it would hide a real problem.

Finding	Why the Doctor will not change it
There are several Start blocks	Which one is the real beginning is a decision about what the workflow is for.
A test block has no test chosen	Which test belongs in a step is the point of the step.
A step points at a test that no longer exists	The Doctor will not choose a replacement for you — but it will list candidates (see Step 5).
One output has two outgoing connectors	Which one you meant cannot be guessed.
A value comes from a step that runs later	Reordering the flow changes what the workflow does.
A step has failed every time the workflow ran	Rewiring would hide the failure. The fix belongs to the step's own test, its data, or the environment. Use run failure analysis on the run instead.
A value is extracted but never used; the workflow has never run; a requirement step is missing; nothing checks beyond status codes	These are advisory. They are worth knowing, not wrong.

Step 5 — Replace a step whose test was deleted

When a step points at a test that was deleted or moved, the finding "Step" points at a test that no longer exists includes a picker of tests that could stand in that step.

Open the list under the finding (it starts at Select a test…; nothing is pre-selected).
Review the options. Each shows the test name and, because a workflow can span projects, the project it belongs to. The most probable replacement is marked likely match — usually a regenerated test carrying the deleted test's name.
Select a test. A line appears explaining why it is a candidate.
Click Use this test for the step.
The confirmation reads "Test name" now runs at this step — save to keep it. Click Save.

If there is nothing to offer, the panel says why — for example, the block records no endpoint, or the endpoint has no tests yet. When the list is long, it shows the most recently updated tests on that endpoint.

Tip: After you choose a test, the Doctor checks again. Pointing a step at a real test often reveals data findings that were hidden while the step had nothing to call.

Step 6 — Ask the assistant about the workflow

At the bottom of the panel, Ask about this workflow opens a conversation about this workflow with the project assistant. Suggested starters include Diagnose what is wrong with this workflow, Show where each step gets its data from and Explain why the last run failed.

The assistant uses the same findings and the same explanations as the panel. It can also offer a fix as a card that you accept. Because the assistant has no canvas open, an accepted fix is saved to the workflow directly, and the same add-only rules apply.

If none of the workflow's steps points at a test that still exists, the Doctor cannot tell which project the workflow belongs to and the conversation will not open. Select the project in the sidebar, or give a step a test first.

Troubleshooting

Symptom	Why it happens	What to do
The Check workflow button is missing	The workflow has never been saved.	Save it once, then the button appears.
A fix appeared, but it is gone after I closed the editor	Canvas fixes are not saved until you click Save.	Apply the fix again and click Save.
A step's test changed even though I did not save	That was the extraction half of a data fix, which is saved to the test immediately.	This is expected. The connector half still needs saving.
The Doctor flags a `{{token}}` that I set elsewhere	The variable is not set by an earlier step and is not in the project's environment variables.	Define it in the project's environment, or feed it from an earlier step.
A finding I expected is not listed	The panel read the canvas when it opened.	Click Check again.
The conversation section says it cannot tell which project the workflow belongs to	Every step points at a deleted test.	Replace a step's test (Step 5) or select the project in the sidebar.

Best practices

Run Check workflow before your first run and after any large edit — data problems do not stop a save, but they make runs fail.
Fix findings in severity order. Blocking findings can hide data findings behind them.
When a step "has failed every time it ran," investigate the step's test and environment rather than the wiring.
Let the Doctor add extractions instead of hand-typing response paths; it only binds values on clear evidence (same name, or an ID from the endpoint named after that entity).
Save after applying fixes, and re-run the workflow to confirm.

For administrators (self-hosted installations)

Setting	Default	What switching it does
`WORKFLOW_DOCTOR_ENABLED`	`true`	Set to `false` to turn workflow checking off. The panel then reports that checking is turned off for this installation.

Creating and Running Workflows

Product documentation

Build End-to-End Workflows Automatically