Troubleshooting: Flow Not Starting
If your flow isn't appearing for users, the specific cause depends on which of these scenarios matches your situation. Find your scenario below and follow the targeted debugging steps.
Scenario 1: Flow Never Appears (Not Even in Preview)
Symptoms:
Flow doesn't show in production
Flow doesn't show in preview/debugger
No sign of the flow anywhere
Most likely causes:
1. Userflow isn't installed on the page
Check: Open browser Console → type userflow → press Enter
If you see ReferenceError: userflow is not defined, the Userflow script hasn't loaded
Fix: Add the Userflow installation snippet to your page's <head> tag
2. userflow.identify() hasn't been called
Userflow won't show any flows until you identify the current user
Check Console for errors mentioning identify
Fix: Call userflow.identify('USER_ID', { attributes }) after Userflow loads
3. Flow isn't published
Check the flow's status in your Userflow dashboard
Fix: Click Publish in the flow editor
4. Flow is published to wrong environment
If you have multiple environments (staging, production), make sure the flow is published to the environment your page is using
Check: Dashboard → Flow → Settings → Published Environments
Fix: Publish to the correct environment
Scenario 2: Flow Appears in Wrong Place or at Wrong Time
Symptoms:
Flow appears, but on the wrong URL
Flow triggers too early or too late
Flow shows on page load when it should trigger on button click (or vice versa)
Most likely causes:
1. URL targeting is too broad or too narrow
Check: Dashboard → Flow → Start Conditions → URL
Common mistake: Using "Contains" instead of "Exact match"
Fix: Test your URL pattern in the Debugger. Use wildcards (*) for dynamic parts of the URL (e.g., /users/*/profile)
2. Start condition timing is wrong
"On page load" triggers immediately when the page loads
"Manual" requires a JavaScript call: userflow.start('FLOW_ID')
Fix: Update Start Conditions in the flow editor to match your intended trigger
3. Hidden conditions are blocking the flow
Hidden conditions let you suppress flows for users who've already seen them (or based on other logic)
Check: Flow editor → Start Conditions → Hidden Conditions
Fix: Test with a fresh user or temporarily remove hidden conditions to isolate the issue
Scenario 3: Flow Works in Preview But Not in Production
Symptoms:
Flow appears correctly when you use the preview link
Flow appears correctly in the Debugger
Flow doesn't appear on the live site for real users
Most likely causes:
1. Flow isn't published to production environment
Preview and Debugger bypass environment checks
Check: Dashboard → Flow → Settings → Published Environments
Fix: Publish to "Production" (or your live environment)
2. Targeting rules exclude real users
Preview often uses your admin account, which may have attributes real users don't have
Example: Flow targets "Role = Admin" but real users have "Role = User"
Check: Flow editor → Start Conditions → Audience
Fix: Update audience rules or test with a realistic user account
3. Production site uses a different Userflow environment token
Your staging and production sites should use different Userflow tokens
Check your production page source for the Userflow snippet — is it using the production token?
Fix: Update the token in your production deployment
Scenario 4: Flow Worked Before But Stopped
Symptoms:
Flow was working yesterday/last week
No changes on your end
Suddenly stops appearing
Most likely causes:
1. Flow was unpublished or paused
Check: Dashboard → Flows → Status column
Look for "Draft" or "Paused" instead of "Published"
Fix: Re-publish the flow
2. Hidden condition now excludes all users
Example: "Has not seen Flow X" → everyone has now seen it
Check: Flow editor → Start Conditions → Hidden Conditions
Fix: Reset hidden conditions or adjust the logic (e.g., "Not seen in last 30 days")
3. Page structure changed (element-based triggers only)
If your flow triggers when a specific button appears, and that button's HTML changed, Userflow might not find it anymore
Check: Flow editor → Start Conditions → Element triggers
Fix: Update the element selector to match the new HTML structure
Scenario 5: Preview Updates But Changes Don't Show on Live Site
Symptoms:
You edited the flow in Userflow dashboard
Preview shows the new version
Live site still shows the old version (or nothing)
Most likely causes:
1. Changes weren't published
After editing a flow, you must click Publish for changes to go live
Fix: Click Publish in the flow editor
2. Browser cache is serving old version
Fix: Hard refresh (Ctrl+Shift+R on Windows, Cmd+Shift+R on Mac) or test in Incognito/Private browsing
3. CDN caching the old Userflow script
If you use a CDN in front of your site, it may cache the Userflow.js file
Fix: Wait 5-10 minutes, then try again; or purge your CDN cache
Still Having Issues?
If none of the above scenarios match your situation:
Open the Userflow Debugger: Click the Userflow icon (bottom-right corner when logged in) and enable "Debug mode"
Check the Console: Look for errors or warnings mentioning Userflow
Contact support: Send your Console output, flow ID, and a description of the issue to support@userflow.com