--- title: "Flow not starting" slug: "flow-not-starting" description: "Troubleshoot your Userflow.js issues with this guide: check installation, flow conditions, and user settings to ensure smooth auto-start functionality." updated: 2026-06-08T17:19:17Z published: 2026-06-08T17:19:17Z --- > ## Documentation Index > Fetch the complete documentation index at: https://help.userflow.com/llms.txt > Use this file to discover all available pages before exploring further. # Flow not starting # 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. ## Before you debug: pre-flight checklist Five quick checks that resolve roughly half of all "flow not starting" cases. If any of these fails, you've likely found the cause. 1. **Open the page where the flow should start.** In your browser console, type `userflow` and press Enter. If you see `ReferenceError: userflow is not defined`, Userflow.js isn't installed on this page. 2. **Confirm**`userflow.identify()`**has been called.**In the console, run `userflow.isIdentified()`. If it returns `false`, the user hasn't been identified — no flows can show. (Returns `true` once `userflow.identify()` or `userflow.identifyAnonymous()` has run on the current page.) 3. **Confirm the flow is published in the environment you're testing.** Open the flow → Settings → Published Environments. Production preview uses your production token; staging preview uses staging. 4. **Open the Userflow Debugger Chrome extension on the page.** Check Verify Setup. If anything shows red, that's your starting point. 5. **Check the user's Sessions tab.** If the user has already seen the flow and the frequency setting is "Only start once per user," the flow won't re-trigger without resetting the session. If all five pass and the flow still isn't starting, work through the scenarios below by symptom. ## 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 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 ## Scenario 6: Flow disappears right after a click or interaction **Symptoms:** - The flow appears, then vanishes the moment the user clicks a button, navigates, or interacts with your app. - The flow seems to "flash" and disappear. **Most likely causes:** 1. **A step has an Advance/Continue trigger that matches immediately.** If the step advances on an element click or a URL change that's already true on arrival, the flow moves on (or completes) instantly. Check: open the step → Triggers, and confirm the trigger only matches *after* the intended user action. Fix: tighten the trigger (e.g. require a specific element click rather than "any click"). 2. **A click navigates to a URL the flow no longer targets.** If the interaction changes the page and the next step's URL conditions don't match, the flow ends. Fix: review the step's page conditions, or use a wildcard so the flow survives the navigation. 3. **A dismiss action is wired to the wrong button.** Check the step's buttons → Actions for an unintended "Dismiss flow" action. ## Environment-specific troubleshooting The most common cause of "works in staging, not in production" is a token or environment mismatch. Specifically: | Symptom | Likely cause | Fix | | --- | --- | --- | | Works in Debugger, not on live site | Flow published to staging but not production | Flow → Settings → Published Environments → enable Production | | Works for you, not for real users | Auto-start condition requires an attribute only you have (e.g., `role: admin`) | Open the flow's conditions; test against a non-admin user's attributes in the Debugger | | Worked yesterday, not today | A targeting attribute or segment definition changed | Compare the user's current attributes to flow conditions in the Debugger | | Works on `/page1`, not on `/page1?query=value` | URL targeting uses Exact match instead of Contains or pattern | Flow → Start Conditions → URL → change to Contains or use `/page1*` wildcard | ## Common auto-start condition mistakes - **Boolean vs. string mismatch.** `"true"` (string) does not match `true` (boolean). Check your `userflow.identify()` call — JSON booleans need to be sent as actual booleans, not strings. - **Case sensitivity.** Attribute names and event names are case-sensitive. `userRole` and `userrole` are different attributes. - **Group attributes without**`userflow.group()`**.** Company-level conditions only work if your app calls `userflow.group(companyId, attributes)`. If the group call isn't firing, all company attributes will be empty and conditions will silently fail. - **Timing race conditions.** If your flow has a Wait condition or Delay Start After Previous Flow setting, the flow waits — it isn't broken. Check the Debugger's yellow "temporarily blocked" pill for the specific delay. - **A backgrounded or idle tab does not stop auto-start — a dead session does.** Userflow keeps evaluating and auto-starting flows even when the browser window or tab is in the background, so a backgrounded or idle tab is not on its own the reason a flow won't start. What does prevent auto-start is the absence of a live session: if the Userflow session is flat or has died (for example it was never established, or has ended), there's nothing for a flow to start into. If a flow isn't auto-starting, confirm an active session exists rather than assuming a backgrounded tab is the cause. ## Before escalating to support Have this information ready — it makes resolution 10x faster: - The flow ID and the URL where it should appear - The user ID of someone the flow isn't starting for - A screenshot of the Userflow Debugger's "Check auto-start" output for that flow and user - Browser console output (any errors mentioning `userflow`) - Confirmation that the user has been seen in Users → search by ID ## Still Having Issues? If none of the above scenarios match your situation: 1. Open the Userflow Debugger: Click the Userflow icon (bottom-right corner when logged in) and enable "Debug mode" 2. Check the Console: Look for errors or warnings mentioning Userflow 3. Contact support: Send your Console output, flow ID, and a description of the issue to support@userflow.com