Diagnostics
The Journey Builder continuously validates your flow as you edit it and displays inline diagnostics. Each diagnostic has a severity level (error, warning, or info), a message explaining the issue, and a fix hint with specific instructions. Errors must be resolved before publishing. Warnings are recommended fixes that improve reliability. Info-level tips suggest optional enhancements.
Diagnostics appear inline on the affected node in the canvas and are also summarized in the diagnostics panel.
Errors
Errors indicate structural problems that will cause the flow to malfunction at runtime. You must fix all errors before publishing the agent.
No entry point
Message: "Flow has no starting node."
Fix hint: Drag a Greeting node from the node palette onto the canvas. This will be the first message users see. Every journey must start with a Greeting node.
Disconnected node
Message: "[Node name] is disconnected from the flow."
Fix hint: This node has no incoming connection. Drag a connection from another node into it, or delete it if it is not needed. A disconnected node will never be reached during a conversation.
Dead-end node
Message: "[Node name] leads nowhere -- add a next step."
A non-terminal node has no outgoing edge, so the conversation will stop unexpectedly. The fix hint varies by node type:
| Node type | Fix hint |
|---|---|
| Greeting | Add a Quick Reply or AI Response after the greeting to guide the conversation. |
| Quick Reply | Connect each option to a next node. You can also loop back to an earlier node like the Greeting. |
| AI Categorizer | Connect each category branch to a next node. Unmatched categories need a path too -- consider looping back to the start. |
| AI Response | Add a Quick Reply, another AI Response, or a Handoff after this. You can also connect back to an earlier node. |
| Question | Connect this to the node that should handle the user's answer -- a Condition, AI Response, or another Question. |
| Condition | Connect both the True and False branches to their next steps. |
| Data Collector | Connect this to the next step -- often a Message confirming what was collected, or a Webhook to send the data. |
| API Call / Webhook | Add a next step after this -- a Message to show the result, or a Condition to branch on the response. |
| Delay / Wait | Connect this to the node that should continue after the wait. |
| Sub-Flow | Connect this to the node that should run after the sub-flow completes. |
| Loop | Connect the "Each item" handle to the nodes that run per iteration, and the "After loop" handle to what happens when the loop finishes. |
| Any other | Drag a connection from this node to any other node. You can connect to a new node, a Handoff to end, or loop back to an earlier node. |
Loop End orphan
Message: "Loop end is not connected to a loop."
Fix hint: Select this Loop End node and set its "Loop Node" property to the Loop node it belongs to. Or delete it if the loop was removed. Every Loop End node must reference the Loop node that owns it.
Circular reference
Message: "Circular connection detected -- infinite loop risk."
Fix hint: There is a loop in your flow with no user interaction to break it, which could run forever. Add a Quick Reply, Question, or AI Categorizer inside the loop so the user controls when it repeats.
Note that cycles through user-interaction nodes (Quick Reply, Question, Data Collector, AI Categorizer) are intentional and allowed -- the user's input naturally breaks the loop. The diagnostics engine only flags cycles that contain no user interaction at all, since those represent true infinite-loop risks.
Warnings
Warnings highlight issues that will not prevent the flow from running but may cause unexpected behavior or a poor user experience.
No error handling
Message: "[Node name] has no error handling -- consider adding it."
Applies to: API Call, Send Email, Fire Webhook, and Webhook nodes.
Fix hint: Click the node and expand Error Handling. Choose what happens if it fails: stop, continue, show a fallback message, or route to an error branch.
Side-effect nodes can fail due to network errors, invalid URLs, authentication issues, or rate limits. Without error handling configured, a failure will stop the flow with no feedback to the user.
Unused condition branch
Message: The "true" (or "false") branch of "[Condition name]" goes nowhere.
Fix hint: Connect the "true" output to the node that should run when the condition is met. Connect the "false" output to a fallback node -- like a Message, AI Response, or loop back to an earlier step.
A Condition node with an unconnected branch means one outcome has no path forward. The user will hit a dead end if the condition evaluates to the unconnected side.
KB not linked
Message: "AI Response uses knowledge base, but none linked."
Fix hint: Go to the Knowledge tab and link at least one knowledge base to this agent, or disable "Use Knowledge Base" on this node.
An AI Response node with useKnowledgeBase enabled cannot retrieve relevant content if the agent has no knowledge bases attached. The AI will still respond, but without the grounding context you intended.
Single input converge
Message: "This converge node has only one input -- not needed."
Fix hint: A Converge node merges multiple branches back together. Connect more branches into it, or remove it and connect directly to the next node.
A Converge node with a single incoming edge adds unnecessary complexity. It functions identically to a direct connection.
Empty loop body
Message: "This loop has no body -- nothing will happen."
Fix hint: Connect the Loop's "each item" output to the nodes that should run for each iteration, ending with a Loop End node.
A Loop node without a body connection will iterate over its data source but do nothing with each item.
Complex flow
Message: "This flow is complex -- consider simplifying."
Trigger: The flow contains 30 or more nodes.
Fix hint: Break this flow into smaller Sub-Flows. Group related steps into their own journey, then use Sub-Flow nodes to compose them together.
Large flows are harder to maintain, debug, and reason about. Sub-flows keep each piece focused and reusable.
Info
Info-level diagnostics are optional suggestions that can improve the effectiveness of your agent.
No lead capture
Message: "Tip: Add a lead capture step to collect visitor information."
Applies to: Knowledge agents that do not have a Data Collector or Lead Capture node.
Fix hint: Drag a Data Collector node into your flow to capture names, emails, or other details from visitors.
This is a gentle suggestion, not a requirement. If your agent is purely informational and does not need visitor data, you can safely ignore it.
Agent-type diagnostics
Some diagnostics are specific to agent types:
Action agent without trigger
Message: "Action agent workflow has no trigger node."
Fix hint: Add a Schedule, Webhook, or Data Monitor trigger to define when this task runs in the background.
Action agents run autonomously and need a trigger to start. Without one, the workflow has no entry condition.
Knowledge agent with trigger nodes
Message: "Knowledge agent has trigger nodes."
Fix hint: Trigger nodes are designed for background task agents and will not run during normal chat. Remove the trigger nodes or convert this to an Action agent if it should run autonomously.
Node-specific diagnostics
Several node types have their own validation rules:
- Quick Reply: Warns when options are missing route targets or when the options list is empty on a template that expects quick replies.
- AI Categorizer: Warns when category branches are missing route targets or when no fallback route is configured for low-confidence classifications.
- Handoff: Warns when no contact target (email, phone, or URL) is configured.
- Product Card: Warns when no catalog is connected.
- Send Email: Warns when no recipient or subject line is configured.
- Webhook: Warns when no URL is configured.
- Generate Document: Warns when no sections are defined, when sections are missing titles or instructions, or when the node expects a knowledge base but none is attached.