Flow not starting troubleshooting
If you have a flow (or a checklist) that you expect to start, but for some reason it doesn’t, then follow this troubleshooting guide.
Is Userflow.js installed in your app?
Verify that Userflow.js is installed in your app. Without it, nothing will start.
The quickest way to tell if user data is flowing from your app to Userflow is by going to the Users tab in the Userflow UI. If the user you’re signed in to your app with appears near the top of the list (sort by Last Seen descending), then Userflow.js is installed and you can skip the rest of this section.
If not, please check the following:
- Open a new fresh tab in Chrome.
- Open Devtools (press F12 on your keyboard).
- Switch to the Console tab.
- Navigate to your app, where Userflow.js is supposed to be installed.
- Check in the Console to see if there are any noticeable Userflow-related errors. If there are, try to resolve them or reach out to us for help.
- Next, switch to the Network tab.
userflow.jsand verify that
Finally, filter by
e.userflow.comand verify that a WebSocket connection is opened to
Make sure you’re not in a Preview tab
Make sure you’re not in a “Preview tab” (the tab that Userflow opens when you click Preview or Select element in the builder). This tab may be running as a fake test user, and not as the real user you’re signed in to your app with.
To make sure: Close the tab that your app is open in. Open a new fresh tab and navigate to your app again.
Is your flow published in the user’s environment?
Go to the builder in Userflow. Check that the flow is published in the same environment you’re viewing your app in.
If the Publish button is disabled, it’s fully published in all environments.
If the button is not disabled, try to click it to see if any unpublished changes have been made, and consider publishing them.
Does the flow have auto-start condition enabled?
Flows only start automatically if you switch “Auto-start flow if…” ON in the builder:
Make sure that it’s turned ON (the switch button is green) and that you’ve added a suitable condition.
Has the user already seen the flow?
By default, flows are configured to Only start once per user (see this setting under the auto-start condition in the builder). That means if the user has already seen the flow, it will not auto-start again.
Find your user under the Users tab in the Userflow UI, switch to the Sessions tab and check if the user has already seen the flow:
If they have, then that’s why it won’t start again. If you want to test the auto-start condition again, you can either delete the whole user or delete just the flow session.
Does the user match the auto-start condition?
Double-check that the user actually matches the flow’s auto-start condition:
- Find your user under the Users tab in the Userflow UI, and verify that any attribute conditions match.
- If you’re using event conditions, look through the user’s Activity feed and verify that the right events have (or have not) been tracked.
If you’re using group or group membership attributes/events, also make sure that
userflow.group()is called in your app and that the group matches the conditions.
Does the flow have “Temporarily hide flow if…” enabled?
If your flow builder has the Temporarily hide flow option enabled, make sure that it’s not the cause for why the flow isn’t showing:
If the user matches this condition, the flow will not start, and even if it has previously started and not been dismissed, it will be temporarily hidden until the condition no longer matches.
Run through the same list as in the previous section, but this time make sure the user doesn’t match the conditions.
Is the user stuck on another flow on a hidden step?
Flows may only auto-start if no other flow is currently active. Check if the user is currently viewing another flow, but is stuck on a Hidden step.
Find your user under the Users tab in the Userflow UI, switch to the Sessions tab and check if any other flows are listed as active with a green play button. If there is another active flow session, then notice which step they’re currently on. Then go to the builder for that flow, and find that step. If it’s a Hidden step, then that’s the reason why your flow won’t auto-start.
Be careful with hidden steps! Hidden steps have 1 rule: They MUST have a trigger that eventually matches and either takes the user to a non-hidden step or dismisses the flow. Otherwise, the user may get stuck and nothing else can auto-start.
If this is your problem, please first fix the hidden step by adding a trigger that always matches. Also reconsider if you really need the hidden step? Often, hidden steps can be deleted and their triggers moved to the previous step.
You can manually end or delete the stuck flow session via the Userflow UI to fix the stuck user this time.
Still not working?
If you’ve gone through this guide and you still can’t get your flow to start, then please reach out to us and provide the following info:
- Confirm that a Userflow employee may add themselves to your account so we can inspect the flow and the user.
- Which flow do you expect to start? Provide the link to the flow’s builder.
- Which user(s) do you expect the flow to start for? Provide links to their profile in the Userflow UI.