Troubleshooting

Troubleshooting

Learn how to troubleshoot common issues with the Kulu SDK and find solutions to problems you may encounter.

Debug Mode

Enable debug mode to show a reset button in the command bar for testing purposes.

const kulu = new Kulu('YOUR_SDK_KEY', { debug: true });

What Debug Mode Does

• Adds a reset button in the command bar (top-right corner)
• Allows you to reset workflow progress without creating new accounts
• Useful for testing workflows repeatedly during development

Check SDK Status

Use these properties to check the current status of your SDK instance:

console.log('Version:', kulu.version);
console.log('Resources loaded:', kulu.resourcesLoaded);
console.log('User initialized:', kulu.userInitialized);
console.log('Valid SDK key:', kulu.isValidSdkKey);
console.log('Available workflows:', kulu.loadedWorkflows);

Common Issues

SDK not initializing?

Symptoms:

• SDK instance is created but nothing happens
• No UI appears on the page

Solutions:

1. Check your SDK key is correct

   if (!kulu.isValidSdkKey) {
     console.error('Invalid SDK key - please check your dashboard');
   }
   

2. Verify resources are loaded before calling init()

   // Wait for resources
   while (!kulu.resourcesLoaded) {
     await new Promise(resolve => setTimeout(resolve, 100));
   }
   
   // Then initialize (end_user_type_id must be created in portal first)
   await kulu.init(userId, description, 'default');
   

3. Check for console errors

   • Open browser DevTools (F12)
   • Look for error messages in the Console tab

UI not appearing?

Symptoms:

• SDK initializes successfully but no UI is visible
• No onboarding flows are shown

Solutions:

1. Ensure init() is called after resources load

   // ❌ Wrong - calling init too early
   const kulu = new Kulu('YOUR_SDK_KEY');
   await kulu.init(userId);  // Resources might not be loaded yet
   
   // ✅ Correct - wait for resources first
   const kulu = new Kulu('YOUR_SDK_KEY');
   while (!kulu.resourcesLoaded) {
     await new Promise(resolve => setTimeout(resolve, 100));
   }
   await kulu.init(userId, 'description', 'default');
   

2. Check userInitialized is true

   console.log('User initialized:', kulu.userInitialized);
   

3. Verify isValidSdkKey is true

   console.log('Valid SDK key:', kulu.isValidSdkKey);
   

4. Check if workflows are available

   console.log('Available workflows:', kulu.loadedWorkflows);
   

Duplicate UI appearing?

Symptoms:

• Multiple instances of the Kulu UI appear on the page
• Command bar appears multiple times

Solutions:

1. Use global window.kuluInstance pattern

   // ❌ Wrong - creates new instance every time
   useEffect(() => {
     const kulu = new Kulu('YOUR_SDK_KEY');
     // ...
   }, [user]);
   
   // ✅ Correct - reuse existing instance
   useEffect(() => {
     if (!window.kuluInstance) {
       window.kuluInstance = new Kulu('YOUR_SDK_KEY');
     }
     // ...
   }, [user]);
   

2. Check for duplicate init() calls

   // Prevent duplicate initialization
   if (window.kuluInstance?.userInitialized) {
     console.log('Already initialized');
     return;
   }
   
   await window.kuluInstance.init(userId, description);
   

3. Properly cleanup on unmount

   useEffect(() => {
     // Initialize...
     
     return () => {
       if (window.kuluInstance) {
         window.kuluInstance.destroy();
         window.kuluInstance = null;
       }
     };
   }, []);
   

Workflows not loading?

Symptoms:

• SDK initializes but no workflows are available
• loadedWorkflows is empty

Solutions:

1. Check if workflows are configured in your dashboard

   • Log in to your Kulu dashboard
   • Verify that you have created and published workflows

2. Verify the SDK key belongs to the correct project

   console.log('SDK Key:', 'YOUR_SDK_KEY');
   console.log('Loaded workflows:', kulu.loadedWorkflows);
   

3. Check network requests

   • Open browser DevTools → Network tab
   • Look for failed requests to api.heykulu.ai
   • Check for CORS or CSP errors

Content Security Policy (CSP)

If your website uses a strict Content Security Policy (CSP), you may need to add directives to allow Kulu to function properly.

Required CSP Directives

Add the following directive to allow onboarding videos to load:

media-src 'self' https://api.heykulu.ai data: blob:;

How to Add CSP Directives

Option 1: HTTP Header

Add to your server's HTTP response headers:

Content-Security-Policy: media-src 'self' https://api.heykulu.ai data: blob:;

Option 2: Meta Tag

Add to your HTML <head>:

<meta http-equiv="Content-Security-Policy" 
      content="media-src 'self' https://api.heykulu.ai data: blob:;">

Option 3: If you already have a media-src directive

Just append our domains to your existing directive:

media-src 'self' your-existing-domains.com https://api.heykulu.ai data: blob:;

Testing CSP Configuration

1. Open browser DevTools → Console
2. Look for CSP violation errors
3. Verify videos load correctly in your onboarding flows

Still Having Issues?

If you're still experiencing problems after trying these solutions:

1. Check the API Reference for correct usage
2. Review the Setup Guide for your framework
3. Contact support at support@heykulu.ai

When contacting support, please include:

• Your SDK version (kulu.version)
• Browser and version
• Console error messages
• Steps to reproduce the issue