Troubleshooting Port Conflicts in WAIIDE

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

Issue: “ERROR: the Jupyter server could not be started because port 8071 is not available”

This error occurs when both WAIIDE Server and jupyterhub-singleuser try to use the same port.

Root Cause

The spawner is misconfigured and sets conflicting port values:

JUPYTERHUB_PORT=8070                        # Correct default
JUPYTERHUB_SERVICE_URL=http://0.0.0.0:8071  # Wrong! Should be 8070

Solution

1. Fix Spawner Configuration

Update your JupyterHub spawner to use consistent ports:

# In your jupyterhub_config.py or spawner configuration
c.Spawner.environment = {
    'JUPYTERHUB_PORT': '8070',
    # Don't set JUPYTERHUB_SERVICE_URL - let JupyterHub handle it
}

# Or if you must set it, ensure it matches:
c.Spawner.environment = {
    'PORT': '8070',
    'JUPYTERHUB_SERVICE_URL': 'http://0.0.0.0:8070'  # Match the PORT
}

2. Container Auto-Adjustment (v2.1+)

The latest WAIIDE container automatically detects and fixes port conflicts:

⚠️  Port conflict detected: PORT (8071) = VSCODE_PORT (8071)
🔧 Adjusting WAIIDE port to 8072

3. Manual Override

If needed, you can manually set different ports:

docker run -e PORT=8070 -e VSCODE_PORT=8072 calliopeai/waiide:latest

Verification

Check the logs for correct port assignment:

🔧 Port configuration:
   Main service port: 8070
   WAIIDE port: 8071

Prevention

1. Use Default Ports: Let WAIIDE use its defaults (8070/8071)
2. Don’t Override SERVICE_URL: Let JupyterHub set this automatically
3. Test Locally: Run test-ecs-local.sh before deploying

Related Issues

• Extension loading errors (node_modules, types) - These are harmless warnings
• OAuth module warnings - These are optional and can be ignored