> For the complete documentation index, see [llms.txt](https://operator-ai.gitbook.io/start/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://operator-ai.gitbook.io/start/conversation-errors/flow-troubleshooting.md).

# Flow Troubleshooting

If a Flow isn’t working as expected in Operator AI, a few quick checks usually solve the issue — here’s how to troubleshoot and fix Flow problems fast.

***

### 🔄 Common Flow Issues

| Problem                             | Likely Cause                                     |
| ----------------------------------- | ------------------------------------------------ |
| **Flow doesn’t start**              | Missing or incorrect trigger setup.              |
| **Flow gets stuck or loops**        | Missing buttons, quick replies, or exit paths.   |
| **Wrong Flow triggered**            | Automation or keyword mismatch.                  |
| **User input not recognized**       | Flow expecting buttons but user typed free text. |
| **Agent handoff inside Flow fails** | Handoff step missing agent assignment.           |

✅ Most Flow issues are simple logic errors — not technical bugs.

***

### 🛠️ How to Troubleshoot a Flow

| Step                            | Action                                                                   |
| ------------------------------- | ------------------------------------------------------------------------ |
| 1. Test the Flow manually       | Start the Flow yourself and simulate user paths.                         |
| 2. Review the trigger setup     | Confirm the Flow is connected to an Automation, keyword, or user action. |
| 3. Inspect button/choice logic  | Ensure users have clear, tappable choices at each step.                  |
| 4. Check for exit conditions    | Confirm the Flow has a clear end point or handoff.                       |
| 5. Watch for missing conditions | Make sure “if/then” branches properly route users.                       |

✅ Follow the user journey fully — not just the ideal path.

***

### 🔥 Fast Fixes for Common Flow Problems

| Problem                     | Fast Fix                                                                 |
| --------------------------- | ------------------------------------------------------------------------ |
| Flow doesn’t launch         | Add a test trigger manually (e.g., keyword = "testflow").                |
| Looping without end         | Add a button to close or escalate the conversation.                      |
| Wrong answer path triggered | Rebuild buttons to have clear, unique payloads.                          |
| Stuck after user input      | Add a fallback after expecting input in case users don’t reply properly. |
| Handoff step fails          | Confirm an agent, department, or queue is assigned at that step.         |

✅ Tiny tweaks fix 90% of broken Flows immediately.

***

### 📋 Best Practices for Reliable Flows

| Tip                                            | Why It Matters                                           |
| ---------------------------------------------- | -------------------------------------------------------- |
| Always test every path                         | Don’t assume users will always click the "right" button. |
| Keep Flows short and simple                    | More steps = more places for user drop-off.              |
| Use quick replies over free text when possible | More control, fewer interpretation errors.               |
| Label each Flow clearly                        | "Support → Billing Flow" instead of "Flow #2".           |
| Update Flows based on conversation history     | Real conversations show where users get stuck.           |

✅ Regular maintenance = smooth, scalable automation.

***

### 🛟 Need Help?

* Explore Flow Building and Testing tutorials inside this documentation.
* Contact <support@heyoperator.ai> for help diagnosing tricky Flow issues.
* Your Success Manager can also run a Flow Audit and suggest improvements.

✅ We’re here to help you make flawless customer journeys.

***

## 🎯 Next Step

👉 [Continue to Fallback Handling Problems →](/start/conversation-errors/fallbacks.md)