Flow doctor

The flow doctor is a static analysis pass that runs over your assistant's conversation graph before you publish. It catches the kinds of problems a schema validator can't see — dead-end paths, infinite loops, slots with no recovery path, intents with no training data, and tool calls with no error handling — and explains each one in plain English. Convoship's pipeline will not let an assistant with blocking issues go live, so fixing them here keeps your release on track.

How to run the flow doctor

1. Open the assistant in the flow builder.
2. Click Run flow doctor in the toolbar (stethoscope icon), or open the Flow doctor panel from the side rail.
3. The doctor scans your graph and lists any issues it finds, ranked by severity.
4. Click Highlight node on a finding to jump to the affected node on the canvas.
5. Fix each blocking issue, then publish as normal.

Severity levels

Rules the doctor checks

Slot with no fallback path (error)

An entity (slot) node that is required must have a way out when the user repeatedly gives an unrecognized answer. Without a fallback, the bot re-prompts forever and the user is stuck. Fix: set an 'On max attempts' target in the slot's inspector, or add a global fallback node to the flow.

Dead-end node (error)

A non-terminal node with no outgoing edge silently ends the conversation mid-task — the user sees nothing further and has no way to continue. Fix: connect the node to the next step, or change it to an End or Handoff node if the conversation is meant to stop there.

Intent with no outgoing path (warning)

An intent node that matches user input but leads nowhere. The bot recognizes what the user said and then does nothing. Fix: connect the intent to a response or sub-flow.

Loop with no exit (error)

A group of nodes where every path leads back into the same loop. The runtime's step limit will eventually trip and the user sees an internal error. Fix: add a branch — a decision, a fallback node, or an edge to any node outside the loop — so there is always a way out.

Intent with no training phrases (warning)

An intent with no example utterances can only match on its literal name, which is brittle. The matcher has nothing to generalize from, so real user phrasing often misses. Fix: add a few varied example phrases in the Intents tab so the matcher can recognize how users actually say this.

Tool call with no error-handling path (warning)

A service or tool node with only a single 'happy path' edge. If the call times out or returns an error, the conversation continues as if it succeeded — with missing or empty data. Fix: add a second branch whose label or condition references 'error' or 'failure', or route the error path to a Fallback or Handoff node.

AI explanations

When an AI key is configured in your workspace, the flow doctor attaches a plain-English explanation to each finding — one short sentence describing the real-world impact on an end user and the recommended fix, written for a non-technical product owner. An 'Explained by AI' label appears at the top of the findings list when explanations are active. Without a key, all rule messages are still returned; only the explanations are omitted.

Publish gate

Every time you publish an assistant, Convoship automatically runs the flow doctor in the background. If any finding is at error severity, the publish is blocked and the response includes the full list of issues. The flow builder surfaces these as a blocked-publish banner so you can fix them before trying again. Warnings do not block publish.

Flow doctor vs. the schema validator

The schema validator and the flow doctor run independently. Both can block publish on their respective error findings. Fix schema errors first (they surface in the Validate panel), then run the flow doctor.