Troubleshooting Common Foundry VTT Issues

Overview

This article covers the most common Foundry VTT server issues encountered in panel and dedicated server environments. Start by checking the Foundry log files, which contain detailed error messages for most failure modes.

Log File Location

/foundry-data/Logs/

In Pterodactyl/WISP containers:

/home/container/data/Logs/

You can also view logs in real time from the panel console, or tail them directly:

tail -f /foundry-data/Logs/foundry.log

Server Won't Start

Symptom: The process exits immediately or no port is opened.

Check 1: Node.js version

node --version

Foundry v14 requires Node.js 24. Foundry v10–v13 requires Node.js 20–22. If the version is wrong, the server will crash on startup with a syntax or compatibility error.

Check 2: Port already in use

ss -tlnp | grep 30000

If another process is already on port 30000, Foundry will fail to bind. Change the port in your startup arguments or stop the conflicting process.

Check 3: Data path missing or incorrect

If the --dataPath directory does not exist or Foundry does not have write permission, startup will fail. Verify:

ls -la /foundry-data/

Check 4: Corrupted options.json

If options.json contains invalid JSON, Foundry will fail to parse it. Validate the file:

node -e "JSON.parse(require('fs').readFileSync('/foundry-data/Config/options.json','utf8'))"

If it throws an error, restore the file from backup or delete it (Foundry recreates it with defaults on next start).

Players Cannot Connect

Symptom: Foundry is running but players get connection refused or timeout.

Check 1: Firewall

Verify the port is open:

# On the server
ss -tlnp | grep 30000

# From an external machine
nc -zv <server-ip> 30000

Open the port if blocked. See Port Configuration and Firewall Setup.

Check 2: Wrong port in invitation URL

If proxyPort is not set correctly in options.json, invitation links will contain the wrong port. Check Configuring Foundry VTT with options.json.

License Activation Fails

Symptom: "Unable to verify license" or network error on the activation screen.

Test outbound connectivity from the server:

curl -I https://foundryvtt.com

If this fails, the server cannot reach Foundry's license server. Check outbound firewall rules or proxy settings.

For Pterodactyl environments using a Timed URL: verify the URL has not expired. Timed URLs are valid for approximately one hour. Generate a fresh URL if needed.

Setup Screen Requires Password (Forgotten)

Stop the server, delete the admin password hash, and restart:

rm /foundry-data/Config/admin.txt

The Setup screen will be accessible without a password. Set a new password immediately. See Setting Up and Resetting the Admin Password.

World Won't Load / Stuck on Loading Screen

Check 1: Browser console errors

Open browser developer tools (F12) → Console tab. Module JavaScript errors often appear here and identify the problematic module.

Check 2: Disable all modules

If a world loads slowly or not at all, a module conflict is the most likely cause. Connect to the world, disable all modules through Settings → Manage Modules, then re-enable them one at a time to identify the culprit.

Check 3: World data corruption

Check Foundry logs for database errors. If a world's database files are corrupted, restore from a snapshot or backup. See Backing Up and Restoring Your Foundry Data.

High Memory Usage / Server Out of Memory

Foundry's Node.js process uses more memory with more active modules and larger worlds. If you see OOM errors:

1. Reduce active modules
2. Increase the Node.js heap size:

   node --max-old-space-size=4096 main.mjs --dataPath=/foundry-data
   

3. Upgrade server RAM

See Performance Tuning and Player Capacity.

Audio/Video Not Working

Voice and video require HTTPS. If players report that the browser is not requesting microphone or camera permission, the server is not running over HTTPS.

Verify:

• The player's browser URL shows https://
• proxySSL: true is set in options.json
• nginx is configured with WebSocket upgrade headers

See Setting Up SSL/HTTPS with nginx.

WebSocket Disconnections

Frequent disconnections ("Lost connection to server" messages) are usually caused by:

• Missing WebSocket headers in nginx config (Upgrade, Connection)
• Proxy timeout settings too short — increase proxy_read_timeout in nginx
• Network instability between players and server

Check the nginx configuration and confirm WebSocket headers are present.

Related

• Configuring Foundry VTT with options.json
• Port Configuration and Firewall Setup
• Setting Up SSL/HTTPS with nginx
• Performance Tuning and Player Capacity