Troubleshooting & Diagnostics¶

This guide provides solutions to common setup, authentication, and network issues encountered when running Cantus.

1. Spotify Authentication Errors¶

Cause: The SPOTIFY_CLIENT_ID environment variable is either unset, contains extra quotes, or is not registered in the Spotify Developer Dashboard.
Solution: Verify that the 32-character Client ID in .env matches the Developer Dashboard exactly without leading/trailing whitespace.

Cause: The callback URL that Cantus sent does not match the list of Redirect URIs in your Spotify Developer App settings.
Solution:
Check CANTUS_HOST_URL in your .env (e.g. http://localhost:5000 or https://cantus.yourdomain.com).
In the Spotify Developer Dashboard under Settings -> Redirect URIs, ensure ${CANTUS_HOST_URL}/api/auth/spotify/callback (e.g. http://localhost:5000/api/auth/spotify/callback and http://127.0.0.1:5000/api/auth/spotify/callback) is added.
Ensure there is no trailing slash on CANTUS_HOST_URL or redirect URI.

Cause: Browsers aggressively cache WebAssembly scripts, .wasm binaries, and application manifest files across deployments.
Solution:
Perform a hard refresh in your browser to bypass the cache:
- Windows / Linux: Ctrl + Shift + R or Ctrl + F5
- macOS: Cmd + Shift + R
Open Developer Tools (F12), navigate to the Application / Storage tab, and click Clear Site Data.
Ensure the backend container is running and healthy:
```
curl -i http://localhost:5000/api/health
```

Cause: The reverse proxy is killing idle WebSocket connections or failing to send upgrade headers.
Solution:
Verify that your proxy config includes Upgrade $http_upgrade and Connection "upgrade".
Increase proxy_read_timeout and proxy_send_timeout to 300s or higher.
If using Cloudflare, verify that WebSockets is enabled in the Cloudflare Network dashboard.

Cause: Too many requests within a short timeframe.
Mitigation Built into Cantus:
Cantus employs an Adaptive Polling Engine that automatically backs off to 5s intervals when playback is paused, 10s when idle, and completely halts polling when zero clients are connected to a room.
Operator Action:
If sharing an instance among multiple active listeners, ensure non-active browser tabs are closed. Cantus will automatically spin down polling for disconnected rooms.

Diagnostics:
Press D on the client to open the Diagnostics HUD and check NTP Clock Offset.
If offset is > 500ms, the host OS clock on either the server or client is desynchronized.
Solution:
Ensure systemd-timesyncd or chrony NTP service is running on the host server:
```
timedatectl status
```

The backend exposes a health endpoint:

curl -i http://localhost:5000/api/health

Expected JSON response:

{
  "status": "Healthy",
  "version": "1.0.0",
  "activeSessions": 1,
  "database": "Connected"
}

View live structured logs:

docker compose logs -f --tail=100 cantus