Flow not starting

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?

Run through the Userflow.js installation check to verify the installation.

Without Userflow.js installed, nothing will start (except if you preview with test user via the chrome extension).

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 company or company membership attributes/events, also make sure that userflow.group(companyId) is called in your app and that the company 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.

If “Constrain to current company” is enabled, is your app calling userflow.group()?

If the Constrain flow/checklist to current company switch is either not displayed or not enabled, then skip this section.

Check if this setting is enabled under Show advanced settings in the builder:

If it is enabled, then the flow may only start if your app is calling userflow.group(companyId). You can read more about this setting in our Companies guide.

Do you have the locale enabled?

If you are using Localization, you need to enable the locale of the user you are testing with for the flow to start. You do this on the Localization tab of the flow.

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:

1. Confirm that a Userflow employee may add themselves to your account so we can inspect the flow and the user.
2. Which flow do you expect to start? Provide the link to the flow’s builder.
3. Which user(s) do you expect the flow to start for? Provide links to their profile in the Userflow UI.