Troubleshooting

Module not found: @xpectrum/sdk

The SDK is not installed or not resolvable.

Fix:

npm install @xpectrum/sdk

If using a monorepo, make sure you're installing in the correct workspace. Check that @xpectrum/sdk appears in your package.json dependencies.

TypeError: Cannot read properties of undefined (reading 'Room')

The livekit-client dependency is missing or not properly installed.

Fix:

npm install livekit-client

401 Unauthorized

Your API key is invalid, expired, or missing.

Checklist:

• Is the API key correct? Copy it fresh from the admin panel.
• Is the environment variable name correct? (NEXT_PUBLIC_ prefix for Next.js, VITE_ for Vite)
• Did you restart the dev server after changing .env.local?
• Is the key for the right module? (Chat uses Bearer token, Voice uses x-api-key)

403 Forbidden

The app is disabled or your key lacks permissions.

Fix:

• Check the app settings in the Xpectrum admin panel
• Make sure the app is active/enabled
• Verify the API key has the correct permissions

TypeError: Failed to fetch / NetworkError

The SDK can't reach your server.

Checklist:

• Is the baseUrl correct? Try opening it in a browser.
• Is the server running?
• Are there CORS issues? Check the browser console for CORS errors.
• Is there a trailing slash issue? Try with and without /
• Is a VPN or firewall blocking the connection?

CORS Error: No 'Access-Control-Allow-Origin' header

Your server needs to allow requests from your frontend domain.

Fix:

This is a server-side configuration issue. The Xpectrum server must include your domain in its CORS allow list. Contact your server administrator.

Request timeout (30s)

The SDK has a 30-second timeout by default.

Possible causes:

• Server is overloaded or slow to respond
• Network latency is very high
• The AI model is taking too long to start generating

Error: Cannot use import statement outside a module / window is not defined

You're trying to use the SDK in a Server Component. The SDK requires browser APIs and must run client-side.

Fix:

Add 'use client' at the very top of any file that imports from @xpectrum/sdk:

'use client'; // <-- This line is required!

import { XpectrumChat } from '@xpectrum/sdk';

Environment variables are undefined

Next.js env vars must start with NEXT_PUBLIC_ to be available in the browser.

Wrong:

# These are NOT available in the browser!
CHAT_BASE_URL=https://...
CHAT_API_KEY=app-...

Correct:

# These ARE available in the browser
NEXT_PUBLIC_CHAT_BASE_URL=https://...
NEXT_PUBLIC_CHAT_API_KEY=app-...

Hydration mismatch warnings

The SDK creates DOM elements that don't exist during server-side rendering.

Fix:

Always initialize the SDK inside a useEffect hook, which only runs client-side. Never create SDK instances at the module level or during render.

Microphone permission denied

The browser blocked microphone access.

Checklist:

• The user must explicitly click a button to start the call (browser requirement)
• The page must be served over HTTPS (or localhost)
• Check browser settings — the mic may be blocked for your site
• Try a different browser to rule out browser-specific issues

No audio from agent

The call connects but you can't hear the AI agent.

Checklist:

• Check your system volume and audio output device
• Some browsers require a user interaction before playing audio — make sure the call is started from a button click
• Check if the agent is actually connected to the room (look for 'connected' event)
• Check the browser console for WebRTC errors

404 on /tokens/generate

The agent name is not found on the voice server.

Fix:

• Double-check the agentName value
• Make sure the agent exists on your voice server
• Check if the baseUrl is pointing to the correct voice server

Connection state stuck on 'connecting'

The SDK got a token but can't establish the WebRTC connection.

Possible causes:

• Firewall blocking WebRTC connections
• The LiveKit server URL returned by your voice server is unreachable
• Network restrictions (corporate proxy, etc.)

onMessage never fires

You called sendMessage() but nothing happens.

Checklist:

• Did you provide the onMessage callback in the options?
• Check the onError callback — there may be a silent error
• Is the chat instance properly initialized? (Check baseUrl and apiKey)
• Open the browser Network tab and look for the chat-messages request

429 Rate Limited

Too many requests in a short period.

Fix:

• Add a loading state to prevent double-sends
• Disable the send button while a response is streaming
• Contact your admin if you need higher rate limits

1. Check the browser console

Open DevTools (F12) and look at the Console tab. The SDK logs errors with useful context (status codes, error messages).

2. Inspect network requests

Open the Network tab in DevTools. Filter by "Fetch/XHR" or "EventStream" to see SDK requests:

• Look at the request headers — is the auth header present?
• Check the response status and body for error details
• For SSE streams, look at "EventStream" type requests

3. Verify credentials in isolation

Test your API key directly with curl to rule out SDK issues:

# Test Chat API
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://app.yourserver.com/api/v1/site

# Test Voice API
curl -H "x-api-key: YOUR_API_KEY" \
  -X POST "https://api.xpectrum.co/tokens/generate?agent_name=YOUR_AGENT"

4. Use the onError callback

Always provide onError to catch streaming errors that don't throw:

await chat.sendMessage('test', {
  onMessage: (text) => console.log('Message:', text),
  onError: (err) => console.error('Stream error:', err),
  onCompleted: () => console.log('Stream ended'),
});