When you publish a flow with auto-start conditions, Userflow evaluates those conditions for each user on every page load. If your flow isn't appearing as expected, this guide explains how targeting works and how to troubleshoot the most common causes.
How auto-start targeting works
Userflow checks the following in order before starting a flow automatically:
- Environment. The flow must be published in the environment the user is viewing (Production, Staging, etc.).
- Audience conditions. Every attribute, event, and segment condition you set under Auto-start flow must be met.
- Frequency rules. The default setting is "Only start once per user." If the user has already seen the flow, it won't start again unless you change this setting or reset the user's session.
- Flow priority. If a user qualifies for multiple auto-start flows, the highest-priority flow displays first. After it's dismissed, the next flow in priority can appear.
- Active flow check. Only one flow can be active for a user at a time. If the user is mid-flow on another flow (including a flow paused on a hidden step), your flow won't start.
Common reasons a flow doesn't appear
The user already saw the flow. Check the user's Sessions tab in Userflow. If the flow shows a completed or dismissed session, the frequency setting is preventing a restart. To re-trigger: delete the user's flow session from the Sessions tab, or temporarily change the frequency setting to "Multiple times per user" for testing.
The user doesn't match the audience conditions. Find the user in the Users tab and compare their attribute values against each condition in your flow. Pay attention to data types — the string "true" does not match the boolean true. The Userflow Debugger (browser extension) will also show you which specific condition is blocking the flow from starting.
The flow isn't published in the user's environment. Open the flow and check the Publish button. If it shows unsaved changes or the flow isn't enabled for Production, users in that environment won't see it.
Another flow is blocking it. Check the user's Sessions tab for any active sessions on other flows, including flows paused on a hidden step. Only one flow can be active per user at a time.
The flow is set to show only once and has already fired. This is the most common cause of "the flow worked once and never showed again." The session record is preserved even after you make edits — you need to explicitly delete the session or reset the frequency setting.
Company conditions aren't being passed. If your flow uses company-level conditions (e.g., company plan or tier), verify that your Userflow.js implementation calls userflow.group(companyId, attributes) correctly. If the company group call isn't firing, company attributes will be empty and the conditions will fail silently.
What happens when you unpublish and republish a flow
- Unpublishing stops the flow immediately for all users. Active sessions end.
- Republishing does not reset user history. Users who already completed or dismissed the flow won't see it again if the frequency is "Only start once per user."
- To re-show a flow to a user who already saw it, delete their session for that flow from the Sessions tab, or change the frequency setting.
- To reset a flow for all users, you currently need to delete sessions individually or in bulk. Contact Userflow support for bulk session reset options.
Testing your targeting conditions
Use the Userflow Debugger (Chrome extension) to see in real time which conditions are blocking your flow on a specific page and user. Open the Debugger, navigate to the page where the flow should appear, and review the condition evaluation for your flow.
→ See Using the Debugger for auto-start conditions for a full walkthrough.