Troubleshooting & FAQ

Common issues and solutions when using Cueflow.

Messages Not Appearing

Check Message Status

Problem: Message doesn't show to any users.

Solution: Ensure the message is Published, not Draft or Archived.

1. Go to Messages

2. Find your message

3. Check the status badge

4. If Draft, click Publish

Check Targeting Rules

Problem: Message shows to some users but not others.

Solution: Review your targeting rules.

1. Open the message

2. Go to Targeting tab

3. Verify rules match your intended audience

4. Test with a known matching user

Common issues:

• Rule values don't match exactly (case-sensitive)

• AND vs OR logic confusion

• Overly restrictive rules excluding everyone

Check Scheduling

Problem: Message not appearing even though published.

Solution: Check start/end dates.

1. Open the message

2. Check the Schedule section

3. Verify:

   • Start date has passed (in UTC)

   • End date hasn't passed

   • Or dates are empty for "always on"

Check Embed Script

Problem: No messages appear at all.

Solution: Verify the embed script is installed correctly.

1. Open browser DevTools (F12)

2. Go to Console tab

3. Look for Cueflow errors

4. Check Network tab for API calls to cueflow.so

Common issues:

• Wrong Workspace ID

• Script not loaded

• Cueflow.init() not called

• Missing user id

Check Dismissals

Problem: Message appeared once, now doesn't show.

Solution: User may have dismissed it.

Once dismissed, messages don't reappear for that user. To test:

• Use a different test user

• Create a new message for testing

Embed Script Issues

"Cueflow is not defined"

Problem: JavaScript error when calling Cueflow methods.

Solution: Script hasn't loaded yet.

// Wait for script to load
window.addEventListener('load', () => {
  Cueflow.init({ id: 'user-123' });
});

// Or check if defined
if (typeof Cueflow !== 'undefined') {
  Cueflow.init({ id: 'user-123' });
}

"user.id is required"

Problem: Error when calling Cueflow.init().

Solution: Pass a valid id field.

// Wrong
Cueflow.init({ email: '[email protected]' });

// Correct
Cueflow.init({
  id: 'user-123',  // Required!
  email: '[email protected]'
});

"Already initialized"

Problem: Warning when calling init multiple times.

Solution: Only call Cueflow.init() once per page load.

// Use a flag to prevent double init
if (!window.cueflowInitialized) {
  Cueflow.init({ id: 'user-123' });
  window.cueflowInitialized = true;
}

Events Not Tracking

Problem: Cueflow.track() doesn't record events.

Solution: Ensure init completed first.

// Wrong - track before init completes
Cueflow.init({ id: 'user-123' });
Cueflow.track('signup'); // May not work

// Correct - events are queued automatically
// Cueflow handles this, but ensure init is called first

Also check:

• Event key matches exactly (case-sensitive)

• User has a valid contact ID

• No console errors

SPA Navigation Issues

Problem: Messages don't update on page change.

Solution: Cueflow auto-detects History API changes. If not working:

// Manually trigger check after navigation
router.afterEach(() => {
  Cueflow.check();
});

Dashboard Issues

Can't Find My Message

Problem: Message not in the list.

Solution: Check filters and status.

1. Clear any active filters

2. Check All status (not just Published)

3. Search by message name

4. Check you're in the correct workspace

Can't Edit Message

Problem: Edit button doesn't work or changes don't save.

Solution:

• Check your role (Members can edit, view role cannot)

• Refresh the page

• Check for browser extensions blocking

Analytics Not Updating

Problem: View/click counts not changing.

Solution: Analytics may take a moment to update.

• Wait a few seconds and refresh

• Check the message is Published

• Verify users are being tracked (have contact IDs)

Targeting Problems

Rule Not Matching

Problem: Targeting rule should match but doesn't.

Solution: Check exact values.

1. Values are case-sensitive: "Pro" ≠ "pro"

2. Check for extra spaces

3. Verify the property exists on the contact

Too Many/Few Matches

Problem: Message shows to wrong audience.

Solution: Review rule logic.

• Same group = AND (all must match)

• Different groups = OR (any can match)

Test with specific users to debug.

Feedback Issues

User Can't Submit Again

Problem: User wants to change their response.

Solution: By design, each user can only respond once.

• One response per user per feedback survey

• Create a new survey if you need fresh responses

Responses Not Appearing

Problem: Submitted feedback not in dashboard.

Solution:

• Check the Responses tab on the feedback message

• Ensure the survey is Published

• Verify the user was identified (has contact ID)

Checklist Issues

Items Not Auto-Completing

Problem: Automatic completion not working.

Solution: Verify the completion rule.

1. Open the checklist item

2. Check completion type is "Automatic"

3. Verify the event key matches exactly

4. Ensure the event was tracked

Checklist Won't Show

Problem: Checklist doesn't appear.

Solution:

• Check targeting rules

• Verify user hasn't completed all items already

• Check the checklist is Published

Account & Access

Can't Access Workspace

Problem: Workspace not visible or access denied.

Solution:

• Check you're logged into the correct account

• Contact workspace admin for invitation

• Check invitation hasn't expired

Invitation Expired

Problem: Invitation link doesn't work.

Solution:

• Ask admin to send a new invitation

• Invitations expire after 7 days

Wrong Role

Problem: Can't perform certain actions.

Solution:

• Contact workspace admin to change your role

• Admins have full access, Members have limited access

API Issues

401 Unauthorized

Problem: API returns unauthorized error.

Solution: Check your API key.

# Verify Authorization header format
Authorization: Bearer sk_your_api_key_here

• Key should start with sk_

• Check key hasn't been deleted

• Verify key is for the correct workspace

429 Rate Limited

Problem: Too many requests error.

Solution: Slow down your requests.

• Limit: 100 requests/minute per API key

• Add delays between batch operations

• Check X-RateLimit-Remaining header

404 Not Found

Problem: Contact or resource not found.

Solution:

• Verify the external ID exists

• Check you're using the correct workspace API key

• Create the contact first if it doesn't exist

Getting Help

Check Documentation

Most issues are covered in our docs. Use search (Cmd/Ctrl+K) to find specific topics.

Contact Support

If you're still stuck:

• Describe the issue in detail

• Include steps to reproduce

• Share any error messages

• Note your browser and environment

FAQ

Can I show multiple messages at once?

Yes, different message types can appear simultaneously (e.g., banner + checklist). However, only one modal can show at a time.

Do messages work offline?

No, Cueflow requires an internet connection to fetch and display messages.

Can I target anonymous users?

Yes, generate a persistent anonymous ID and use it for tracking. Update to a real ID after signup.

How long is data retained?

Contact and event data is retained indefinitely. Message analytics are kept for the lifetime of the message.

Can I export my data?

Yes, contacts can be exported to CSV. Feedback responses can also be exported.

Is there an API for everything?

The public API covers contacts and events. Message management is through the dashboard.

Can I use custom CSS?

The embed script injects its own styles. Custom CSS isn't currently supported, but message colors are fully customizable.

Does Cueflow affect page performance?

The embed script is lightweight (~30KB) and loads asynchronously. It shouldn't noticeably impact page load times.