If your Flow or Checklist doesn’t start, follow this guide to troubleshoot and resolve the issue.
Is Userflow.js installed in your app?
Run through the Userflow.js installation check to verify the installation.
Without Userflow.js installed, nothing starts (except when previewing with a 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 test user, not as the real user you’re signed in as.
How to verify: Close the tab that your app is open in. Open a new tab and navigate to your app again.
Is your Flow published in the user’s environment?
Open the Flow builder and ensure it is published in the same environment as the app you’re viewing (e.g., Production vs. Staging). If the Publish button is disabled, the item is fully published across all environments.
If the button is not disabled, click it to see if any unpublished changes have been made, and consider publishing them.
Is auto-start enabled for the Flow?
Flows start automatically only if you enable Auto-start flow in the builder and have added at least one valid 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?
If a Flow with an auto-start condition doesn’t start for a user, ensure the user matches the auto-start condition:
Find the user in the Users tab in Userflow, and verify that all 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 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 of why the Flow isn’t showing:
If the user meets this condition, the Flow will not start. 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 ensure the user doesn’t meet the conditions.
Is the user currently viewing another Flow on a hidden step?
Flows will only auto-start if no other Flow is currently active. Check whether the user is viewing another Flow on a Hidden step.
Find the user in the Users tab in Userflow, 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 note which step they’re currently on. Then go to the builder for that Flow and find that step. If it’s a Hidden step, that’s why your Flow won’t auto-start.
Be careful with hidden steps! Hidden steps have one main 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 the issue, first fix the hidden step by adding a trigger that always matches. Or, you may reconsider if a Hidden step is the best option for your Flow.
You can manually end or delete the stuck Flow session in Userflow to alleviate the issue for the user.
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, 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 set the user's locale in the Localization tab of the Flow for the Flow to start.
Still not working?
If you’ve gone through this guide and you still can’t get your Flow to start, then please contact our support team (support@userflow.com or chat with us) and provide the following information:
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.