Common Issues and Solutions

Calliope Integration: This component is integrated into the Calliope AI platform. Some features and configurations may differ from the upstream project.

Container Startup Issues

Container exits immediately

Symptoms:

• Container starts then stops within seconds
• No services accessible

Causes & Solutions:

1. Permission issues

   # Check container logs
   docker logs <container-name>
   
   # Look for: "Failed to change to home directory"

   Solution: Ensure volume permissions are correct:

   # Fix volume ownership
   docker run --rm -v jupyterhub-user-username:/data busybox \
     chown -R 1000:100 /data

2. Port conflicts

   # Check if port 8080 is in use
   lsof -i :8080

   Solution: Stop conflicting service or use different port mapping

WAIIDE Server won’t start

Symptoms:

• API returns but WAIIDE shows 502 error
• /api/services shows WAIIDE as “stopped”

Debugging:

# Check WAIIDE Server directly
docker exec <container> curl -I http://localhost:8081

# Check WAIIDE logs
docker exec <container> tail -f /home/*/WAIIDE-server/logs/*.log

Common fixes:

• Increase container memory limit (WAIIDE needs ~1GB minimum)
• Wait 15-20 seconds for WAIIDE to fully initialize

JupyterHub Integration Issues

404 Not Found on API endpoints

Symptoms:

• /user/username/api returns 404
• Container is running but not accessible

Cause: Environment variables not passed correctly

Solution: Verify spawner doesn’t override environment:

# Don't do this:
c.DockerSpawner.environment = {}  # This clears JupyterHub vars!

# Do this instead:
c.DockerSpawner.environment.update({
    'MY_VAR': 'value'
})

OAuth 403 Forbidden Error

Symptoms:

• “User {username} is not allowed”
• Happens with named servers

Solution: See OAuth 403 Fix Guide

Quick fix:

# Disable named servers
c.JupyterHub.allow_named_servers = False

Container spawns but redirects fail

Symptoms:

• Container starts successfully
• Browser shows connection errors
• Manual access to container port works

Cause: Network configuration issue

Solution: Ensure correct network setup:

# Hub and containers must be on same network
c.DockerSpawner.network_name = 'jupyterhub-network'
c.DockerSpawner.use_internal_ip = True

Access and Authentication Issues

Can’t access WAIIDE interface

Symptoms:

• API works but WAIIDE doesn’t load
• Blank page or loading spinner

Debugging steps:

1. Check browser console for errors

2. Verify WebSocket connectivity:

   // In browser console
   new WebSocket('wss://' + location.host + location.pathname.replace(/\/$/, '') + '/ws')

3. Check for CSP headers blocking resources

Solutions:

• Clear browser cache and cookies
• Try incognito/private mode
• Check for proxy/firewall blocking WebSocket

Assets fail to load (CSS/JS missing)

Symptoms:

• WAIIDE loads but looks broken
• Console shows 404 for static assets

Cause: URL rewriting not working properly

Solution: Verify service prefix is set:

# Inside container
docker exec <container> env | grep JUPYTERHUB_SERVICE_PREFIX

Should show: /user/username/ or similar

Performance Issues

Slow initial load

Normal behavior: WAIIDE Server takes 10-20 seconds to start initially

Optimization tips:

1. Increase CPU limit:

   c.DockerSpawner.cpu_limit = 4

2. Pre-warm containers (advanced):

   # Start container before user logs in
   c.Spawner.pre_spawn_hook = my_prewarm_function

High memory usage

WAIIDE Server baseline memory: ~500MB-1GB

Solutions:

1. Set appropriate limits:

   c.DockerSpawner.mem_limit = '4G'
   c.DockerSpawner.mem_guarantee = '2G'

2. Limit extensions loaded

Debugging Tools

Check container health

# View running processes
docker exec <container> ps aux

# Check service status
curl http://localhost:8080/api/services

# Monitor resource usage
docker stats <container>

Enable debug logging

# Set in spawner environment
c.DockerSpawner.environment = {
    'LOG_LEVEL': 'DEBUG'
}

# Or runtime
docker exec <container> bash -c "export LOG_LEVEL=DEBUG"

Test API endpoints

# From host (with port mapping)
curl http://localhost:8080/api

# From within container
docker exec <container> curl http://localhost:8080/api

# With JupyterHub prefix
curl http://hub:8000/user/username/api

Container Recovery

Restart services without container restart

WAIIDE Server:

# Kill and restart WAIIDE
docker exec <container> pkill -f "node.*server-main.js"
# It will auto-restart via API server

API Server (standalone mode):

docker exec <container> pkill -f "python.*api_server.py"
# Need container restart

Extract user data

# Backup workspace
docker cp <container>:/home/username/workspace ./backup

# Or use volumes
docker run --rm -v jupyterhub-user-username:/data \
  -v $(pwd):/backup busybox \
  tar czf /backup/user-data.tar.gz /data

Known Limitations

1. Named servers: OAuth scope issues (use workaround)
2. Extensions: Limited to web-compatible extensions only
3. Terminal: Some shell features may not work in web terminal
4. File uploads: Large files (>100MB) may timeout
5. Clipboard: Copy/paste requires HTTPS in some browsers

Getting Help

If issues persist:

1. Collect diagnostics:

   docker logs <container> > container.log
   docker exec <container> env > container-env.txt
   curl http://localhost:8080/api/services > services.json

2. Check GitHub issues: https://github.com/CalliopeAI/calliope-WAIIDE/issues

3. Enable debug mode and reproduce the issue

4. Include JupyterHub version and configuration