WAIIDE Troubleshooting

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

This section helps resolve common issues with WAIIDE deployment and operation.

🚨 Quick Fixes

Issue	Quick Solution	Details
WAIIDE not loading	Check container logs for errors	Container Issues
OAuth 403 errors	Verify named server configuration	OAuth Issues
Multiple instances not working	Enable `allow_named_servers`	Multi-Instance Issues
Container won’t start	Check spawner configuration	Spawner Issues

📋 Common Issues

Container Issues

Container Startup Problems - Container won’t start or crashes
Permission Issues - File access and ownership problems
Resource Limits - Memory and CPU constraints

Authentication Issues

OAuth Problems - 403 errors and authentication failures
Named Server Auth - Multi-instance authentication issues
Token Issues - API token problems

Configuration Issues

Spawner Configuration - JupyterHub spawner problems
Environment Variables - Variable configuration issues
Network Configuration - Port and networking problems

🔧 Diagnostic Tools

Container Diagnostics

# Check container status
docker ps | grep waiide

# View container logs
docker logs <container-name>

# Execute commands in container
docker exec -it <container-name> bash

# Check environment variables
docker exec <container-name> env | grep JUPYTERHUB

JupyterHub Diagnostics

# Check JupyterHub logs
journalctl -u jupyterhub -f

# Check spawner status
curl http://hub:8081/hub/api/users/<username>/servers

# Test API endpoints
curl http://hub:8081/hub/api/info

WAIIDE-Specific Diagnostics

# Check WAIIDE API
curl http://localhost:8080/api

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

# Check WAIIDE health
curl http://localhost:8071/

🐛 Debugging by Symptom

“Container Starts But WAIIDE Won’t Load”

Check port configuration:
```
docker exec <container> netstat -tlnp
```

Verify WAIIDE process:

docker exec <container> ps aux | grep WAIIDE

Check proxy configuration:
```
docker logs <container> | grep proxy
```

“OAuth 403 Forbidden Errors”

Check server name:
```
echo $JUPYTERHUB_SERVER_NAME
```
Verify callback URL:
```
echo $JUPYTERHUB_OAUTH_CALLBACK_URL
```

Check OAuth scopes:

echo $JUPYTERHUB_OAUTH_ACCESS_SCOPES | jq .

“Multiple Instances Not Working”

Check named servers setting:

# In jupyterhub_config.py
print(c.JupyterHub.allow_named_servers)

Verify server limits:

print(c.JupyterHub.named_server_limit_per_user)

Check container naming:
```
print(c.DockerSpawner.name_template)
```

“Wrong URLs or Paths”

Check service prefix:
```
echo $JUPYTERHUB_SERVICE_PREFIX
```

Verify default URL:

# In jupyterhub_config.py  
print(c.Spawner.default_url)

Check proxy configuration:

docker exec <container> cat ~/.jupyter/jupyter_server_config.py

📊 Log Analysis

Log Levels

# Enable debug logging
-e LOG_LEVEL=DEBUG

# Filter logs by component
docker logs <container> 2>&1 | grep "waiide-api"
docker logs <container> 2>&1 | grep "jupyterhub"
docker logs <container> 2>&1 | grep "WAIIDE"

Key Log Messages

Message	Meaning	Action
`Running as named server: <name>`	Instance name detected	✅ Working correctly
`OAuth fix for named servers loaded`	OAuth patches applied	✅ Working correctly
`WAIIDE Server is ready`	WAIIDE started successfully	✅ Working correctly
`Failed to connect to my Hub`	Can’t reach JupyterHub API	❌ Check API URL
`Missing required environment $JUPYTERHUB_SERVICE_URL`	Environment variable missing	❌ Check spawner config

🔍 Performance Troubleshooting

Memory Issues

# Check memory usage
docker stats <container-name>

# Check container limits
docker inspect <container-name> | grep -i memory

CPU Issues

# Check CPU usage
docker stats <container-name>

# Check process CPU usage
docker exec <container> top

Storage Issues

# Check disk usage
docker exec <container> df -h

# Check volume mounts
docker inspect <container-name> | grep -A 5 Mounts

🚑 Emergency Procedures

Container Recovery

# Restart container
docker restart <container-name>

# Force recreate container  
docker stop <container-name>
docker rm <container-name>
# Let JupyterHub respawn it

Data Recovery

# Access user data from host
docker run -it --rm -v <user-volume>:/data ubuntu:latest bash

# Backup user data
docker run --rm -v <user-volume>:/data -v $(pwd):/backup ubuntu tar czf /backup/user-backup.tar.gz /data

Clean Reinstall

# Remove all WAIIDE containers
docker ps -a | grep waiide | awk '{print $1}' | xargs docker rm -f

# Remove volumes (WARNING: Data loss)
docker volume ls | grep user- | awk '{print $2}' | xargs docker volume rm

# Pull latest image
docker pull calliopeai/waiide:latest

📞 Getting Help

Before Asking for Help

✅ Check this troubleshooting guide
✅ Review the Configuration Guide

✅ Collect diagnostic information:

# System information
docker version
docker info

# Container logs
docker logs <container-name> > waiide-logs.txt

# Configuration
cat jupyterhub_config.py

Support Channels

GitHub Issues: Report bugs and feature requests
Documentation: Check other sections for related information
Community: Engage with other users and developers

📖 Related Documentation

Configuration - Prevent issues with proper configuration
Architecture - Understand system behavior
Development - Debug and extend WAIIDE

💡 Pro Tip: Enable debug logging (LOG_LEVEL=DEBUG) for detailed troubleshooting information!

WAIIDE Technical Overview WAIIDE Workspace Sharing via JupyterHub