Skip to main content

Troubleshooting

Common issues and solutions across all UG Labs SDKs and APIs.

SDK-Specific Troubleshooting​

General Issues​

Connection Issues​

WebSocket connection fails

  • Verify your API key is correct
  • Check network connectivity and firewall settings
  • Ensure you're using the correct environment URL:
    • Staging: wss://pug.stg.uglabs.app
    • Production: wss://pug.uglabs.app
  • WebSocket requires HTTPS (secure context) for voice features

Authentication Errors​

"Invalid API key" or 401 errors

  1. Verify the API key from UG Labs Console
  2. Check that the key hasn't expired or been revoked
  3. Ensure you're using the correct key for your environment (staging vs production)

"Unauthorized federatedId"

  1. Ensure the federatedId matches your registered user ID pattern
  2. Check that your application is correctly registered in the Console

Audio Issues​

Microphone not working

  1. Grant microphone permissions when prompted
  2. Ensure HTTPS (required for WebRTC/microphone access)
  3. Try using headphones to avoid echo
  4. Check browser console for specific permission errors

Safari doesn't record or play audio

Safari requires HTTPS for voice recording and playback. When developing locally:

  1. Start your local dev server with HTTPS enabled:
    • Vite: vite --https
    • Create React App: HTTPS=true npm start
    • Next.js: Use next dev --experimental-https or configure a local certificate
  2. Accept the self-signed certificate warning in Safari
  3. Grant microphone permissions when prompted

This is a Safari-specific security requirement and doesn't affect Chrome or Firefox in local development.

No audio output

  1. Check system volume and audio output device
  2. Verify capabilities.audio: true in configuration
  3. Check browser console for audio playback errors

Performance Issues​

High latency responses

  1. Check network connection quality
  2. Consider using onOutputUtilities instead of onInputUtilities (non-blocking)
  3. Review prompt complexity - shorter prompts respond faster

Memory usage growing

  1. Ensure you're calling dispose() when conversations end
  2. Check for event listener leaks (remove listeners when components unmount)

Getting Help​

If you can't resolve your issue:

  1. Check the WebSocket Protocol documentation for API details
  2. Review the JavaScript SDK Configuration reference
  3. Contact UG Labs support with:
    • Error messages (include error IDs if shown)
    • SDK version
    • Browser/platform information
    • Steps to reproduce