Skip to main content

Troubleshooting

Common issues and solutions for Kaltura Avatar SDK and API.

Session Creation Issues​

Error: "Invalid Kaltura Session"​

Symptoms:

  • 401 Unauthorized error
  • "Invalid Kaltura Session" message

Solutions:

  1. Verify Kaltura Session is correct
  2. Check Authorization: KS <ks> header is set correctly
  3. Ensure Kaltura Session is active (not expired)
  4. Contact Kaltura for new session if needed
// ❌ Wrong
headers: {
  'api-key': KS // Wrong header name
}

// ✅ Correct
headers: {
  Authorization: `KS ${KS}`
}

Error: "Session not found"​

Symptoms:

  • 404 Not Found error
  • "Session not found" message

Solutions:

  1. Verify sessionId is correct
  2. Check if session was already ended
  3. Ensure session was created successfully
  4. Check session hasn't expired

WebRTC Connection Issues​

Avatar video not displaying​

Symptoms:

  • Black screen in avatar container
  • No video element created
  • Connection state stuck at "CONNECTING"

Solutions:

1. Check browser support​

// Check WebRTC support
if (!navigator.mediaDevices || !RTCPeerConnection) {
  console.error('WebRTC not supported in this browser');
}

2. Check container exists​

// Make sure container exists BEFORE calling createSession
const container = document.getElementById('avatar-container');
if (!container) {
  console.error('Container not found!');
}

3. Check firewall/network​

  • Try on different network
  • Check if corporate firewall blocks WebRTC
  • Test with iceTransportPolicy: 'relay'
const session = new KalturaAvatarSession(apiKey, {
  baseUrl: '...',
  iceTransportPolicy: 'relay', // Force TURN servers
});

Connection timeout​

Symptoms:

  • Connection never reaches "CONNECTED"
  • Timeout after 30 seconds

Solutions:

  1. Check TURN servers are accessible
# Test TURN server connectivity
telnet turn.example.com 443
  1. Try relay-only mode
const session = new KalturaAvatarSession(apiKey, {
  baseUrl: '...',
  iceTransportPolicy: 'relay',
});
  1. Check network restrictions
  • Corporate firewall may block WebRTC
  • VPN may interfere
  • Try on different network

API Request Issues​

Error: "Token expired"​

Symptoms:

  • 401 Unauthorized after some time
  • "Invalid or expired token" message

Solutions:

  1. Tokens are tied to session lifetime
  2. Create new session if token expired
  3. Don't reuse tokens across sessions
// ❌ Wrong - reusing old token
const oldToken = localStorage.getItem('token');
const session = new KalturaAvatarSession(oldToken, config);

// ✅ Correct - create new session
const { sessionId, token } = await createNewSession();
const session = new KalturaAvatarSession(token, config);

Error: "CORS policy blocked"​

Symptoms:

  • CORS error in browser console
  • Request blocked by browser

Solutions:

  1. For development: Use CORS proxy or configure backend
// Backend (Express)
import cors from 'cors';
app.use(
  cors({
    origin: 'http://localhost:3000',
    credentials: true,
  })
);
  1. For production: Ensure API server sends correct CORS headers

Rate limit errors​

Symptoms:

  • 429 Too Many Requests error
  • Requests failing after many calls

Solutions:

  1. Implement rate limiting on your side
  2. Add delays between requests
  3. Cache session info
  4. Contact Kaltura to increase limits

SDK Issues​

Module not found​

Symptoms:

Cannot find module '@unisphere/models-sdk-js'

Solutions:

  1. Install the package
npm install @unisphere/models-sdk-js
  1. Clear cache and reinstall
rm -rf node_modules package-lock.json
npm install
  1. Check import path
// ✅ Correct
import { KalturaAvatarSession } from '@unisphere/models-sdk-js';

// ❌ Wrong
import { KalturaAvatarSession } from 'unisphere-models-sdk-js';

TypeScript errors​

Symptoms:

  • Type errors in IDE
  • Cannot find type declarations

Solutions:

  1. Types are included - no @types needed
  2. Restart TypeScript server in your IDE
  3. Check tsconfig.json:
{
  "compilerOptions": {
    "moduleResolution": "node",
    "esModuleInterop": true
  }
}

Browser-Specific Issues​

Safari​

Issue: Video doesn't play automatically

Solution: User interaction required first

// Wait for user click
document.getElementById('start-btn').addEventListener('click', async () => {
  await session.createSession({ ... });
});

iOS Safari​

Issue: Video element not fullscreen

Solution: Use playsinline attribute (SDK does this automatically)

<video playsinline autoplay />

Firefox​

Issue: Permission prompts for media devices

Solution: Normal Firefox behavior - user must allow permissions

Performance Issues​

High CPU usage​

Symptoms:

  • Browser/tab becomes slow
  • High CPU in task manager

Solutions:

  1. End unused sessions
// Always clean up
await session.endSession();
  1. Limit concurrent sessions
// Don't create too many sessions at once
if (activeSessions.length >= 3) {
  console.warn('Too many active sessions');
  return;
}
  1. Check for memory leaks
// Properly remove event listeners
session.on('error', errorHandler);
// Later...
session.off('error', errorHandler);

Slow video loading​

Symptoms:

  • Long time to connect
  • Video stuttering

Solutions:

  1. Check network speed
# Test connection speed
speedtest-cli
  1. Use TURN servers (automatic in SDK)
  2. Check server location - closer is better

Debugging Tips​

Enable debug logging​

const session = new KalturaAvatarSession(apiKey, {
  baseUrl: '...',
  logLevel: 'debug', // See all logs
});

Check connection state​

session.on('connectionChange', (state) => {
  console.log('Connection state:', state);

  if (state === 'FAILED') {
    console.error('Connection failed!');
    // Check network, firewall, TURN servers
  }
});

Monitor session state​

session.on('stateChange', (state) => {
  console.log('Session state:', state);

  if (state === 'ERROR') {
    console.error('Session error!');
    // Check Kaltura Session, session ID, token
  }
});

Check browser console​

Always check browser DevTools console for:

  • Error messages
  • Network requests (failed API calls)
  • WebRTC connection logs

Test with curl​

Test API endpoints directly:

# Create session
curl -X POST https://api.avatar.us.kaltura.ai/v1/avatar-session \
  -H "Authorization: KS $KS" \
  -H "Content-Type: application/json" \
  -d '{"visualConfig": {"avatarId": "avatar-123"}}'

# Say text
curl -X POST https://api.avatar.us.kaltura.ai/v1/avatar-session/$SESSION_ID/say-text \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello!"}'

Still Having Issues?​

  1. Check documentation: Review relevant sections
  2. Check examples: Compare your code with working examples
  3. Enable debug logging: See what's happening internally
  4. Check browser console: Look for error messages
  5. Test network: Try different network/location
  6. Contact support: Reach out to Kaltura with:
    • Error messages
    • Browser console logs
    • Network logs (HAR file)
    • Steps to reproduce

See Also​