Skip to main content

Troubleshooting Guide

Common issues and solutions for ChatSDK 2.0. Find answers in <5 minutes.

Connection Issues​

Issue 1: "Cannot connect to database"​

Error:

Error: Connection refused to localhost:5432
Connection terminated unexpectedly

Cause: PostgreSQL Docker container not running

Solutions:

  1. Check Docker is running:

    docker ps

  2. Start services:

    docker compose up -d

  3. Check PostgreSQL logs:

    docker logs chatsdk-postgres

  4. Verify connection manually:

    psql postgresql://chatsdk:YOUR_PASSWORD@localhost:5432/chatsdk

  5. Reset database (if corrupted):

    docker compose down -v  # ⚠️ Deletes all data!
    docker compose up -d

Issue 2: "WebSocket connection failed"​

Error:

WebSocket connection to 'ws://localhost:8001' failed
Error during WebSocket handshake

Cause: Centrifugo not running or CORS issue

Solutions:

  1. Check Centrifugo is running:

    docker compose ps centrifugo
    curl http://localhost:8001/health

  2. Check logs:

    docker logs chatsdk-centrifugo

  3. Verify configuration:

    cat docker/centrifugo.json

  4. Check firewall:

    # macOS
    sudo lsof -i :8001

    # Linux
    sudo netstat -tlnp | grep 8001

  5. CORS issue (browser console shows):

    // Add to centrifugo.json
    {
      "allowed_origins": ["http://localhost:3000"]
    }

Issue 3: "Token expired" / "401 Unauthorized"​

Error:

Error: JWT token expired
Error: 401 Unauthorized

Cause: Token expired and auto-refresh failed

Solutions:

  1. Token refresh should be automatic in ChatSDK 2.0:

    // Check onTokenRefresh callback is defined
    const sdk = new ChatSDK({
      onTokenRefresh: (tokens) => {
        console.log('Tokens refreshed!'); // Should see this every ~55 min
      },
    });

  2. Check refresh token is valid:

    const tokens = JSON.parse(localStorage.getItem('chatTokens'));
    console.log('Expires at:', new Date(tokens.expiresAt));

  3. Clear tokens and re-authenticate:

    localStorage.removeItem('chatTokens');
    // Redirect to login

  4. Enable debug mode:

    const sdk = new ChatSDK({
      debug: true, // See token refresh logs
    });

Message Issues​

Issue 4: "Messages not sending"​

Error:

Message fails with no error
Message stuck in "sending" status

Cause: Offline, circuit breaker open, or permission issue

Solutions:

  1. Check connection state:

    console.log(sdk.getConnectionState());
    // Should be: 'CONNECTED'

  2. Check network tab in DevTools:

    • Open browser DevTools (F12)
    • Go to Network tab
    • Filter by WS (WebSocket)
    • Send message and watch for errors

  3. Enable debug mode:

    const sdk = new ChatSDK({
      debug: true, // See retry attempts
    });

  4. Check circuit breaker status:

    const state = sdk.getCircuitBreakerState();
    console.log(state); // 'CLOSED', 'OPEN', or 'HALF_OPEN'

  5. Verify permissions:

    const canSend = await sdk.checkPermission({
      channelId: 'ch-abc123',
      permission: 'messages.send',
    });

Issue 5: "Messages not appearing in real-time"​

Error:

Messages don't appear live
Have to refresh to see new messages

Cause: WebSocket not connected or not subscribed to channel

Solutions:

  1. Check WebSocket connection:

    sdk.on('connection.state', (state) => {
      console.log('Connection:', state);
    });

  2. Subscribe to channel:

    sdk.subscribeToChannel({ channelId: 'ch-abc123' });

  3. Check event listeners:

    sdk.on('message.new', (message) => {
      console.log('New message received:', message);
    });

  4. Test with two browser windows:

    • Open localhost:3000?user=alice
    • Open localhost:3000?user=bob in incognito
    • Send message as Alice
    • Should appear in Bob's window instantly

  5. Check Centrifugo logs:

    docker logs -f chatsdk-centrifugo

File Upload Issues​

Issue 6: "File upload fails"​

Error:

413 Payload Too Large
Error uploading file
Upload progress stuck at 0%

Cause: File too large, MinIO not running, or network issue

Solutions:

  1. Check file size:

    const maxSize = 10 * 1024 * 1024; // 10MB default

    if (file.size > maxSize) {
      alert('File too large. Max 10MB.');
      return;
    }

  2. Check MinIO is running:

    docker compose ps minio
    curl http://localhost:9000/minio/health/live

  3. Verify MinIO credentials:

    # .env.local
    S3_ACCESS_KEY_ID=chatsdk
    S3_SECRET_ACCESS_KEY=YOUR_MINIO_PASSWORD

  4. Create bucket manually:

  5. Increase max file size (self-hosted):

    # nginx.conf
    client_max_body_size 50M;

Development Issues​

Issue 7: "Port already in use"​

Error:

Error: listen EADDRINUSE: address already in use :::3000
Port 3000 is already allocated

Cause: Another process using the port

Solutions:

  1. Find what's using the port:

    # macOS/Linux
    lsof -i :3000

    # Windows
    netstat -ano | findstr :3000

  2. Kill the process:

    # macOS/Linux
    kill -9 <PID>

    # Windows
    taskkill /PID <PID> /F

  3. Change port:

    // package.json
    {
      "scripts": {
        "dev": "next dev -p 3001"
      }
    }

  4. Or in .env.local:

    PORT=3001

Issue 8: "npm install fails"​

Error:

EACCES: permission denied
gyp ERR! stack Error: EACCES: permission denied

Cause: Permission issues with npm

Solutions:

  1. Don't use sudo with npm:

    # ❌ Bad
    sudo npm install

    # ✅ Good
    npm install

  2. Fix npm permissions:

    mkdir ~/.npm-global
    npm config set prefix '~/.npm-global'
    echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.profile
    source ~/.profile

  3. Use nvm (recommended):

    curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
    nvm install 18
    nvm use 18

  4. Clear npm cache:

    npm cache clean --force
    rm -rf node_modules package-lock.json
    npm install

Issue 9: "TypeScript errors after update"​

Error:

Property 'xyz' does not exist on type 'Message'
Type 'string' is not assignable to type 'MessageType'

Cause: Breaking changes in SDK update

Solutions:

  1. Update ChatSDK to latest:

    npm install @chatsdk/core@latest @chatsdk/react@latest

  2. Clear node_modules:

    rm -rf node_modules package-lock.json
    npm install

  3. Check migration guide:

    https://docs.chatsdk.dev/migration/v1-to-v2

  4. Restart TypeScript server (VS Code):

    • Cmd+Shift+P → "TypeScript: Restart TS Server"

Docker Issues​

Issue 10: "Docker containers won't start"​

Error:

docker compose up fails
Error response from daemon
Cannot connect to Docker daemon

Cause: Docker not running, disk space, or config issue

Solutions:

  1. Check Docker is running:

    docker ps
    # If error: "Cannot connect to Docker daemon"
    # → Start Docker Desktop

  2. Check disk space:

    docker system df
    docker system prune  # Free up space

  3. Reset Docker Desktop:

    • Docker Desktop → Settings → Reset
    • Choose "Reset to factory defaults"

  4. Check docker-compose.yml syntax:

    docker compose config  # Validate syntax

  5. View logs for specific service:

    docker logs chatsdk-postgres
    docker logs chatsdk-centrifugo
    docker logs chatsdk-redis

Debug Mode​

Enable verbose logging to diagnose issues:

const sdk = new ChatSDK({
  apiUrl: '...',
  userId: '...',

  // Enable debug mode
  debug: true,
});

// Check connection state
console.log('Connection:', sdk.getConnectionState());

// Check circuit breaker
console.log('Circuit breaker:', sdk.getCircuitBreakerState());

// Check queued messages (offline)
const queued = await sdk.getQueuedMessages();
console.log(`${queued.length} messages queued`);

// Check token expiration
const expiration = sdk.getTokenExpiration();
console.log('Token expires in:', expiration.expiresIn, 'seconds');

Getting Help​

1. Check Documentation​

2. Search Issues​

3. Community​

4. Support​

FAQ​

Q: Do I need to configure anything for ChatSDK to work? A: No! ChatSDK 2.0 uses smart defaults. Zero config needed for development.

Q: How do I enable offline mode? A: It's enabled by default! Messages automatically queue when offline.

Q: Why are my tokens expiring? A: Tokens auto-refresh 5 min before expiration. Make sure onTokenRefresh callback is defined.

Q: Can I use ChatSDK with Next.js 14 App Router? A: Yes! ChatSDK 2.0 fully supports App Router, Pages Router, and Server Components.

Q: How do I deploy to production? A: See Production Deployment Guide. Set 3 environment variables minimum.

Q: Is ChatSDK HIPAA compliant? A: Yes, with proper configuration. See HIPAA Compliance Guide.

Q: How do I migrate from v1 to v2? A: See Migration Guide. Most APIs are backwards compatible.

Q: Can I self-host ChatSDK? A: Yes! Docker Compose included. See Self-Hosting Guide.

Still Stuck?​

If you're still experiencing issues:

  1. Enable debug mode and check browser console
  2. Search GitHub issues for similar problems
  3. Ask in Discord - community usually responds <1 hour
  4. Create GitHub issue with:
    • Error message (full stack trace)
    • ChatSDK version
    • Browser/Node version
    • Minimal reproduction steps

We're here to help! 🚀