Troubleshooting

This guide helps you resolve common issues with RKT Chat Client session initialization.

Common Issues

Session Not Initializing

Problem: Session remains in "not ready" state indefinitely.

Symptoms:

• isSessionReady stays false
• sessionId is empty or not generated
• No telemetry initialization

Solutions:

1. Check Browser Compatibility

   // Add this to debug browser support
   console.log('requestIdleCallback supported:', 'requestIdleCallback' in window);
   console.log('setTimeout fallback available:', typeof setTimeout === 'function');

2. Verify Client-Side Rendering

   // Ensure component is running on client-side
   useEffect(() => {
     if (typeof window === 'undefined') {
       console.error('Component running on server-side');
       return;
     }
     // Your initialization logic
   }, []);

3. Check Dependencies

   // Verify all required dependencies are available
   const { chatbot, baseUrl } = options;
   if (!chatbot?.id) {
     console.error('Chatbot ID is required');
   }
   if (!baseUrl) {
     console.error('Base URL is required');
   }

Telemetry Initialization Fails

Problem: Telemetry provider fails to initialize.

Symptoms:

• telemetryInitialized stays false
• Console errors related to telemetry
• Missing device/user data

Solutions:

1. Check Telemetry Provider Implementation

   // Ensure your telemetry provider implements all required methods
   const telemetryProvider = {
     initializeSession: (data) => {
       try {
         // Your implementation
         console.log('Telemetry initialized:', data);
       } catch (error) {
         console.error('Telemetry initialization failed:', error);
       }
     },
     trackEvent: (event, properties) => {
       // Implementation
     },
     trackError: (error, context) => {
       // Implementation
     },
   };

2. Handle Network Errors

   // Add error handling to telemetry calls
   const telemetryProvider = {
     initializeSession: async (data) => {
       try {
         await fetch('/api/telemetry/session', {
           method: 'POST',
           headers: { 'Content-Type': 'application/json' },
           body: JSON.stringify(data),
         });
       } catch (error) {
         console.warn('Telemetry service unavailable:', error);
         // Continue without telemetry
       }
     },
   };

3. Validate Data Structure

   // Ensure data structure matches expected format
   const validateSessionData = (data) => {
     const required = ['chatbotId', 'sessionId'];
     const missing = required.filter(field => !data[field]);
     
     if (missing.length > 0) {
       console.error('Missing required fields:', missing);
       return false;
     }
     return true;
   };

Session ID Generation Issues

Problem: Session ID is not generated or is invalid.

Symptoms:

• sessionId is empty string
• Multiple session IDs generated
• Session ID format is unexpected

Solutions:

1. Check AI SDK Import

   import { generateId } from "ai";
   
   // Verify generateId is working
   const testId = generateId();
   console.log('Generated ID:', testId);

2. Prevent Multiple Generations

   // Ensure session ID is only generated once
   const [sessionId, setSessionId] = useState<string>("");
   
   useEffect(() => {
     if (sessionId === "") {
       const newId = generateId();
       setSessionId(newId);
     }
   }, [sessionId]);

3. Validate Session ID Format

   // Check if generated ID is valid
   const isValidSessionId = (id: string) => {
     return id && id.length > 0 && typeof id === 'string';
   };

onReady Callback Not Triggered

Problem: onReady callback is not called when session is ready.

Symptoms:

• onReady function is not executed
• Session appears ready but callback missing
• Timing issues with callback execution

Solutions:

1. Check Callback Implementation

   const { onReady } = useChat({
     // ... other options
     onReady: (sessionId) => {
       console.log('Session ready callback triggered:', sessionId);
       // Your callback logic
     },
   });

2. Verify Session State

   // Monitor session state changes
   useEffect(() => {
     console.log('Session state changed:', {
       sessionId,
       isSessionReady,
       telemetryInitialized,
     });
   }, [sessionId, isSessionReady, telemetryInitialized]);

3. Handle Async Callbacks

   // If your callback is async, handle it properly
   const handleSessionReady = async (sessionId: string) => {
     try {
       await performAsyncInitialization(sessionId);
       console.log('Async initialization completed');
     } catch (error) {
       console.error('Async initialization failed:', error);
     }
   };

Performance Issues

Problem: Session initialization causes performance problems.

Symptoms:

• UI freezes during initialization
• Slow page load times
• High CPU usage

Solutions:

1. Verify Background Processing

   // Ensure initialization runs in background
   const initializeSessionInBackground = (sessionId: string) => {
     const initSession = () => {
       // Heavy initialization work
       initializeSession(sessionId);
     };
   
     // Use requestIdleCallback for better performance
     if ('requestIdleCallback' in window) {
       window.requestIdleCallback(initSession, { timeout: 5000 });
     } else {
       setTimeout(initSession, 0);
     }
   };

2. Optimize Telemetry Data Collection

   // Collect only necessary data
   const getMinimalDeviceInfo = () => ({
     userAgent: navigator.userAgent,
     language: navigator.language,
     platform: navigator.platform,
     // Skip heavy operations like screen dimensions if not needed
   });

3. Debounce State Updates

   // Prevent excessive re-renders
   const [sessionState, setSessionState] = useState({
     sessionId: '',
     isReady: false,
     telemetryInitialized: false,
   });
   
   // Update state in batches
   const updateSessionState = (updates) => {
     setSessionState(prev => ({ ...prev, ...updates }));
   };

Debugging Tools

Debug Component

Create a debug component to monitor session state:

import React from 'react';
import { useChat } from '@rkt/rkt-chat-client';

const SessionDebugger: React.FC = () => {
  const {
    sessionId,
    isSessionReady,
    telemetryInitialized,
    initializeSession,
  } = useChat({
    chatbot: { id: 'debug-chatbot' },
    baseUrl: 'https://getrocketflow.io/api/chat',
  });

  const [logs, setLogs] = React.useState<string[]>([]);

  const addLog = (message: string) => {
    const timestamp = new Date().toLocaleTimeString();
    setLogs(prev => [...prev, `[${timestamp}] ${message}`]);
  };

  React.useEffect(() => {
    addLog(`Session ID: ${sessionId || 'Not generated'}`);
  }, [sessionId]);

  React.useEffect(() => {
    addLog(`Session Ready: ${isSessionReady ? 'Yes' : 'No'}`);
  }, [isSessionReady]);

  React.useEffect(() => {
    addLog(`Telemetry Initialized: ${telemetryInitialized ? 'Yes' : 'No'}`);
  }, [telemetryInitialized]);

  return (
    <div className="fixed bottom-4 right-4 w-80 bg-white border rounded shadow-lg p-4">
      <h3 className="font-bold mb-2">Session Debug</h3>
      <div className="space-y-1 text-xs max-h-40 overflow-y-auto">
        {logs.map((log, index) => (
          <div key={index} className="font-mono">{log}</div>
        ))}
      </div>
      <button
        onClick={() => setLogs([])}
        className="mt-2 px-2 py-1 bg-gray-500 text-white rounded text-xs"
      >
        Clear Logs
      </button>
    </div>
  );
};

export default SessionDebugger;

Console Debugging

Add comprehensive logging to your implementation:

const debugSessionInitialization = () => {
  console.group('Session Initialization Debug');
  
  console.log('Browser Support:', {
    requestIdleCallback: 'requestIdleCallback' in window,
    setTimeout: typeof setTimeout === 'function',
    window: typeof window !== 'undefined',
  });
  
  console.log('Environment:', {
    nodeEnv: process.env.NODE_ENV,
    isClient: typeof window !== 'undefined',
  });
  
  console.groupEnd();
};

// Call this in your component
useEffect(() => {
  debugSessionInitialization();
}, []);

Error Recovery

Graceful Degradation

Implement fallbacks for when initialization fails:

const useChatWithFallback = (options) => {
  const [fallbackMode, setFallbackMode] = useState(false);
  
  const chat = useChat({
    ...options,
    onError: (error) => {
      console.error('Chat initialization failed:', error);
      setFallbackMode(true);
    },
  });

  if (fallbackMode) {
    return {
      ...chat,
      isSessionReady: true, // Force ready state
      telemetryInitialized: false,
    };
  }

  return chat;
};

Retry Logic

Add retry logic for failed initializations:

const useRetryableSession = (options, maxRetries = 3) => {
  const [retryCount, setRetryCount] = useState(0);
  const [isRetrying, setIsRetrying] = useState(false);

  const chat = useChat({
    ...options,
    onError: (error) => {
      if (retryCount < maxRetries) {
        setIsRetrying(true);
        setTimeout(() => {
          setRetryCount(prev => prev + 1);
          setIsRetrying(false);
        }, 1000 * Math.pow(2, retryCount)); // Exponential backoff
      }
    },
  });

  return {
    ...chat,
    isRetrying,
    retryCount,
  };
};

Browser-Specific Issues

Internet Explorer

Problem: IE doesn't support modern JavaScript features.

Solution:

// Add polyfills for IE
if (!window.requestIdleCallback) {
  window.requestIdleCallback = (callback, options) => {
    const timeout = options?.timeout || 0;
    return setTimeout(callback, timeout);
  };
}

Safari

Problem: Safari has different behavior for certain APIs.

Solution:

// Handle Safari-specific issues
const isSafari = /^((?!chrome|android).)*safari/i.test(navigator.userAgent);

if (isSafari) {
  // Use setTimeout instead of requestIdleCallback
  setTimeout(initSession, 0);
} else {
  window.requestIdleCallback?.(initSession);
}

Mobile Browsers

Problem: Mobile browsers may have limited resources.

Solution:

// Optimize for mobile
const isMobile = /Android|webOS|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini/i.test(navigator.userAgent);

if (isMobile) {
  // Use minimal telemetry data
  const minimalDeviceInfo = {
    userAgent: navigator.userAgent,
    language: navigator.language,
  };
}

Getting Help

If you're still experiencing issues:

1. Check the Console: Look for error messages and warnings
2. Enable Debug Mode: Use the debug component above
3. Test in Different Browsers: Verify cross-browser compatibility
4. Check Network Tab: Ensure API calls are working
5. Review Documentation: Check the API Reference

Common Error Messages