Troubleshooting

View logs

Start here for any issue:

docker compose -f docker-compose.server.yml logs -f realm-server

Add --since 1h to limit output to the last hour.

Common problems

Voice shows 0 bytes / ICE state stuck at new

Cause: UDP ports 40000-49999 are not reachable from the internet.

Fix:

1. Check your VPS firewall. Make sure UDP 40000-49999 is open inbound.
2. If you're using UFW: ufw allow 40000:49999/udp
3. Test it: run nc -u -l 40001 on the server, then nc -u YOUR_SERVER_IP 40001 from another machine.

Voice connects but no audio flows

Cause: REALM_WEBRTC_ANNOUNCED_IP is missing, wrong, or set to a private IP.

Fix: Set it to your server's public IP or a hostname that resolves to it:

REALM_WEBRTC_ANNOUNCED_IP="203.0.113.42"

Restart the server after changing this. A wrong value here means ICE candidates advertise the wrong address, so voice media never reaches the server.

"Cannot start without a server ID"

Cause: The server can't reach Realm on first boot. It needs to register before it can start.

Fix:

1. Check REALM_CORE_API_BASE_URL is set to https://api.realmvoice.app
2. Test outbound connectivity: curl https://api.realmvoice.app/health
3. Check DNS resolution: nslookup api.realmvoice.app

"Running offline"

Cause: The server has a saved identity (server-identity.json) but can't currently reach Realm.

Impact: Existing users with valid session tokens can still connect. New users can't get session tokens until Realm is reachable again.

Fix: Check your outbound firewall rules and DNS. The server reconnects automatically.

"Version not allowed"

Cause: The version of @realm/server you're running has been blocked by the version policy.

Fix:

docker compose -f docker-compose.server.yml pull
docker compose -f docker-compose.server.yml up -d

Connection refused on port 5000

Cause: The container isn't running, or port 5000 isn't open in the firewall.

Fix:

1. Check containers: docker compose -f docker-compose.server.yml ps
2. Check the firewall allows TCP 5000 inbound
3. If you added a reverse proxy, make sure it's running too

WebSocket disconnects frequently

Cause: A reverse proxy timeout. Nginx defaults to 60s with no activity. Caddy is more lenient.

Fix: If using Nginx, add:

proxy_read_timeout 86400s;
proxy_send_timeout 86400s;

Database connection errors

Cause: The server can't connect to its database.

Fix:

1. Check the database is running: docker compose -f docker-compose.server.yml ps mongo
2. Check REALM_STORAGE_MONGO_URL. In Docker Compose the hostname is the service name (mongo), not localhost.
3. Check database logs: docker compose -f docker-compose.server.yml logs mongo

Server registered but disappears from the server list

Cause: The server's heartbeat to Realm failed, marking it offline.

Fix: Check outbound connectivity, then restart:

docker compose -f docker-compose.server.yml restart realm-server

Diagnostic commands

# Container status and uptime
docker compose -f docker-compose.server.yml ps

# Resource usage (CPU, memory)
docker stats realm-server

# Follow logs in real time
docker compose -f docker-compose.server.yml logs -f realm-server

# Check port 5000 is reachable (run from outside your server)
curl http://YOUR_SERVER_IP:5000/metadata

# Test a UDP port (requires netcat on both machines)
# On the server:
nc -u -l 40001
# On your machine:
echo "test" | nc -u YOUR_SERVER_IP 40001

Getting help

1. Collect the server logs: docker compose logs --tail=100 realm-server
2. Note your server version from GET /metadata
3. Reach out via the support channel or contact us directly