Skip to main content

Troubleshooting Overview

This guide provides solutions to common issues encountered when using the social.plus Video SDK. Whether you’re experiencing streaming problems, playback issues, or integration challenges, you’ll find help here.

Quick Diagnostic Steps

1. Check SDK Version

Ensure you’re using the latest version of the social.plus Video SDK:
npm list @social-plus/video-sdk
Update to the latest version:
npm update @social-plus/video-sdk

2. Verify API Key

Confirm your API key is valid and has the correct permissions:
import { SocialPlusVideo } from '@social-plus/video-sdk';

const sdk = new SocialPlusVideo({
  apiKey: 'your-api-key',
  environment: 'production' // or 'sandbox'
});

// Test API key validity
try {
  await sdk.validateApiKey();
  console.log('API key is valid');
} catch (error) {
  console.error('API key validation failed:', error);
}

3. Check Network Connectivity

Test your network connection and firewall settings:
// Test network connectivity
const networkStatus = await sdk.testNetworkConnectivity();
console.log('Network status:', networkStatus);

// Check required ports and protocols
const portsStatus = await sdk.testRequiredPorts();
console.log('Ports status:', portsStatus);

Common Issues and Solutions

Installation Issues

Issue: Package Installation Fails

npm ERR! code ERESOLVE
npm ERR! ERESOLVE unable to resolve dependency tree
Solution:
# Clear npm cache
npm cache clean --force

# Install with legacy peer deps
npm install @social-plus/video-sdk --legacy-peer-deps

# Or use yarn
yarn add @social-plus/video-sdk

Issue: TypeScript Declaration Files Missing

Cannot find declaration file for module '@social-plus/video-sdk'
Solution:
# Install type definitions
npm install @types/social-plus-video-sdk

# Or add to tsconfig.json
{
  "compilerOptions": {
    "skipLibCheck": true
  }
}

Authentication Issues

Issue: API Key Rejected

Error: Invalid API key or insufficient permissions
Solutions:
  1. Verify API key format and characters
  2. Check API key permissions in dashboard
  3. Ensure correct environment (production vs sandbox)
  4. Regenerate API key if compromised
// Debug API key issues
const debugInfo = await sdk.getDebugInfo();
console.log('Debug info:', debugInfo);

Issue: Token Expired

Error: Authentication token has expired
Solution:
// Implement token refresh
sdk.on('tokenExpired', async () => {
  try {
    const newToken = await refreshAuthToken();
    await sdk.setAuthToken(newToken);
  } catch (error) {
    console.error('Token refresh failed:', error);
    // Redirect to login
  }
});

Streaming Issues

Issue: Cannot Start Stream

Error: Failed to initialize camera or microphone
Solutions:
  1. Check browser permissions
  2. Verify camera/microphone availability
  3. Test on different devices
// Check media permissions
const permissions = await sdk.checkMediaPermissions();
console.log('Media permissions:', permissions);

if (!permissions.camera) {
  await sdk.requestCameraPermission();
}

if (!permissions.microphone) {
  await sdk.requestMicrophonePermission();
}

Issue: Poor Stream Quality

Low bitrate, dropped frames, or pixelated video
Solutions:
  1. Check upload bandwidth
  2. Adjust stream settings
  3. Optimize encoding parameters
// Optimize stream settings
await broadcaster.configureStream({
  resolution: '720p', // Reduce from 1080p
  bitrate: 3000, // Adjust based on bandwidth
  fps: 30, // Reduce from 60fps
  keyFrameInterval: 2
});

// Enable adaptive streaming
await broadcaster.enableAdaptiveStreaming({
  minBitrate: 500,
  maxBitrate: 5000,
  adaptation: 'aggressive'
});

Playback Issues

Issue: Video Won’t Play

Error: Unable to load video stream
Solutions:
  1. Check stream availability
  2. Verify network connection
  3. Test different quality settings
// Diagnose playback issues
const playbackDiagnostics = await player.runDiagnostics();
console.log('Playback diagnostics:', playbackDiagnostics);

// Try different quality
await player.setQuality('480p');

// Enable debug mode
player.enableDebugMode(true);

Issue: Audio/Video Sync Issues

Audio and video are out of sync
Solutions:
// Adjust audio delay
await player.setAudioVideoSync({
  audioDelay: 100, // milliseconds
  autoSync: true
});

// Reset stream
await player.resetStream();

Platform-Specific Issues

Web Browser Issues

Issue: WebRTC Not Supported
// Check WebRTC support
if (!sdk.isWebRTCSupported()) {
  console.warn('WebRTC not supported, falling back to HLS');
  await player.configurePlayback({
    protocol: 'hls',
    fallback: true
  });
}
Issue: CORS Errors
Access to XMLHttpRequest blocked by CORS policy
Solution: Configure your server to allow cross-origin requests or use our CDN:
const sdk = new SocialPlusVideo({
  apiKey: 'your-api-key',
  useCDN: true, // Use social.plus CDN to avoid CORS
  corsProxy: 'https://your-cors-proxy.com'
});

Mobile App Issues

Issue: iOS Background Streaming
Stream stops when app goes to background
Solution:
// Configure background modes
await sdk.configureBackgroundMode({
  enabled: true,
  audioOnly: true, // Continue audio in background
  notification: {
    title: 'Live Stream Active',
    text: 'Streaming in background'
  }
});
Issue: Android Permissions
Camera permission denied
Solution:
// Request permissions properly
const permissions = await sdk.requestPermissions([
  'camera',
  'microphone',
  'storage'
]);

if (!permissions.camera) {
  // Show permission explanation
  showPermissionDialog();
}

Performance Optimization

Memory Management

Issue: Memory Leaks

// Proper cleanup
class StreamComponent {
  async componentWillUnmount() {
    // Clean up resources
    await this.player.destroy();
    await this.broadcaster.stop();
    
    // Remove event listeners
    this.sdk.removeAllListeners();
  }
}

Network Optimization

Issue: High Bandwidth Usage

// Optimize for mobile networks
await sdk.configureNetworkOptimization({
  dataSaver: true,
  adaptiveBitrate: true,
  preload: 'none',
  maxBandwidth: 2000000 // 2 Mbps limit
});

Debugging Tools

Enable Debug Logging

// Enable comprehensive logging
sdk.enableDebugLogging({
  level: 'verbose', // 'error', 'warn', 'info', 'debug', 'verbose'
  categories: ['streaming', 'playback', 'network', 'auth'],
  output: 'console' // 'console', 'file', 'remote'
});

Network Diagnostics

// Run network diagnostics
const networkDiag = await sdk.runNetworkDiagnostics();
console.log('Network diagnostics:', networkDiag);

// Test specific endpoints
const endpointTest = await sdk.testEndpoints([
  'streaming',
  'chat',
  'analytics'
]);

Performance Monitoring

// Monitor SDK performance
sdk.on('performanceMetrics', (metrics) => {
  console.log('Performance metrics:', {
    fps: metrics.fps,
    bitrate: metrics.bitrate,
    latency: metrics.latency,
    memoryUsage: metrics.memoryUsage
  });
});

Error Reporting

Automatic Error Reporting

// Enable automatic error reporting
sdk.configureErrorReporting({
  enabled: true,
  includeUserAgent: true,
  includeNetworkInfo: true,
  customData: {
    userId: 'user-123',
    sessionId: 'session-456'
  }
});

Manual Error Reporting

// Report custom errors
try {
  await someSDKOperation();
} catch (error) {
  await sdk.reportError(error, {
    context: 'custom-operation',
    severity: 'high',
    tags: ['streaming', 'user-action']
  });
}

Getting Help

Support Resources

  1. Documentation: Check our comprehensive docs
  2. GitHub Issues: Report bugs and feature requests
  3. Community Forum: Ask questions and share solutions
  4. Support Tickets: For urgent issues or enterprise support

Collecting Debug Information

When reporting issues, please include:
// Collect debug information
const debugInfo = await sdk.collectDebugInfo();
console.log('Debug info to include in support request:', debugInfo);
This includes:
  • SDK version
  • Platform information
  • Browser/device details
  • Network conditions
  • Error logs
  • Performance metrics

Next Steps