🔧 Troubleshooting Guide

Solutions to common Eaglercraft problems.

Connection Issues

❌ Problem: "WebSocket Connection Failed"

Solution 1: Check the URL Format

• ❌ Wrong: ws://example.com:5200
• ❌ Wrong: http://example.com:5200
• ✅ Correct: wss://example.com

Always use wss:// (secure WebSocket).

Solution 2: Verify Server is Running

For Codespaces Docker:
$ docker-compose ps
(Should show "eaglercraft-server" running)

For Sealos:
Check dashboard — app should show "Running"

Solution 3: Check Firewall/School Filters

• WebSocket uses port 443 (HTTPS), which is usually allowed
• Some school networks block specific domain patterns
• Try: Using a VPN (not recommended at school)
• Better: Try at home

Solution 4: Browser Compatibility

• Try a different browser (Chrome → Firefox, etc.)
• Update your browser to latest version
• Clear browser cache: Ctrl+Shift+Delete

❌ Problem: "Connection Timed Out"

Server isn't responding.

• Check if server is still running
• Restart the server
• Check the server logs for errors
• Check your internet connection

❌ Problem: "Can't Connect to [Server URL]"

The domain/URL doesn't exist or is wrong.

• Double-check the URL spelling
• For Codespaces: Make sure the port is "Public"
• Copy-paste the URL instead of typing
• Try the server in your browser first (without wss:// prefix)

Performance Issues

❌ Problem: Very Low FPS

Game is running at 10-20 FPS.

Quick Fixes (Try in Order)

Advanced Fixes

• Enable WASM-GC in browser flags (chrome://flags)
• Update browser to latest version
• Disable hardware acceleration and re-enable it
• Try a different client (Resent vs. CyanogenMC)

❌ Problem: Constant Lag Spikes

FPS drops every few seconds.

• Close Discord (uses lots of resources)
• Stop large downloads/uploads
• Restart your router
• Check your internet speed (ideally 10+ Mbps)
• Try 4G/mobile hotspot to debug

❌ Problem: Stuttering/Freezing Randomly

• Enable VSYNC (Options → Video Settings)
• Lower render distance further
• Disable fancy graphics (use Fast)
• Check if your browser is updated

Gameplay Issues

❌ Problem: World Won't Save

Check if World is Being Saved

• Make changes (break a block, place one, etc.)
• Leave the world (Save & Quit)
• Re-enter world — changes should be there

If World Data is Lost

Possible causes:

• You cleared browser cache/cookies
• Browser local storage was wiped
• You switched browsers
• Temporary browser glitch

Prevention: Export your world regularly as a .ZIP file.

❌ Problem: Can't Place/Break Blocks

• Check server connection (should say "Connected" in top-left)
• Check your game mode (might be in Spectator)
• Rejoin the server
• Restart client

❌ Problem: Mobs Spawning in Peaceful Mode

• You might be on Easy/Normal mode
• Change difficulty: Options → Difficulty
• Save and reload

Audio/Voice Chat Issues

❌ Problem: Voice Chat Not Working

Solution 1: Check Browser Permissions

• Click the camera/mic icon in address bar
• Make sure Microphone is "Allowed"
• If it says "Block", click and change to "Allow"

Solution 2: Check Server Certificate (HTTPS Required)

Voice chat requires HTTPS (secure connection).

• Check URL starts with https://
• Codespaces always uses HTTPS ✅
• Local servers need manual HTTPS setup

Solution 3: Check System Audio

• Make sure microphone isn't muted (check PC volume icon)
• Test in Discord or other app first
• Update audio drivers

❌ Problem: Can't Hear Others

• Check volume slider in-game
• Check system volume is above 10%
• Check speakers aren't broken
• Others might have muted themselves

Client/Download Issues

❌ Problem: Client Won't Launch

• Clear browser cache (Ctrl+Shift+Delete)
• Try a different browser
• Restart computer
• Make sure JavaScript is enabled

❌ Problem: Client Says "Outdated Version"

• Update Eaglercraft client to latest version
• If server is old, use older client version
• Check GitHub releases for version matching

❌ Problem: Antivirus Blocking Eaglercraft

This is a false positive. Official Eaglercraft is safe.

• Add exception to antivirus for the client
• Temporarily disable antivirus (not recommended long-term)
• Use VirusTotal.com to verify the file

Server Issues (For Server Owners)

❌ Problem: Server Crashes on Startup

For Docker (Codespaces):

$ docker-compose logs -f
(Look for red ERROR messages)

Common causes:
- Port already in use: Change port in docker-compose.yml
- Out of memory: Increase allocated RAM
- Image won't pull: Check internet or Docker Hub status

❌ Problem: Players Can't Connect

• Make sure ports 5200/5201 are PUBLIC (not Private)
• Check server logs for connection errors
• Verify domain/URL is correct
• Try connecting locally from same machine first

❌ Problem: World Corruption

• Restart server (usually fixes it)
• Check disk space
• Restore from backup
• Delete world folder and start fresh

Still Stuck?