Troubleshooting & Best Practices - The Foundry VTT Guide

The Troubleshooter's Mindset

Every GM hits technical hiccups. The goal isn't to avoid every problem; it's to handle them calmly. Treat troubleshooting like a detective story: each error message is a clue, and the difference between panic and confidence is knowing where to look.

Most problems in Foundry come from one of a handful of places: the network between you and your players, an add-on module that isn't ready for your Foundry version, a scene that asks too much of someone's computer, or a mistake that a backup can undo. This page is your emergency toolkit and your guide to preventing problems before they start.

The Troubleshooting Framework

Work down the questions until one says yes:

flowchart TD A["Something goes wrong"] --> Q1{"Can players connect?"} Q1 -->|No| C["Connection World launched? Port 30000 forwarded? Test from a phone on mobile data"] Q1 -->|Yes| Q2{"After an update or new module?"} Q2 -->|Yes| M["Modules Safe Configuration, then Find the Culprit!"] Q2 -->|No| Q3{"Slow or laggy?"} Q3 -->|Yes| P["Performance Smaller images, fewer lights, lower Performance Mode"] Q3 -->|No| Q4{"Content missing or damaged?"} Q4 -->|Yes| D["Data Check ownership, then restore a backup"] Q4 -->|No| U["Read the F12 console and ask the community"]

Common Problems and Solutions

The Debug Detective Toolkit

Foundry runs in a web browser, so the browser's developer console is where errors show up. Press F12 in Chrome, Edge or Firefox and open the Console tab.

Launch in Safe Configuration is built into Foundry. From the Setup screen, open your world's menu and choose it: the world starts with all modules disabled, no scene active and audio stopped. It only applies to that one launch, so your normal module list comes back next time. Find the Culprit! is a module (not part of core) that switches modules off in batches until it finds the one causing your problem.

Best Practices for Stability

Stable worlds come from a steady routine rather than heroic rescues:

flowchart TD A["Back up Take Backup of the world before any change"] --> B["Change one thing at a time Stable channel only for live games"] B --> C["Test before game night launch the world, watch the F12 console"] C --> D["Play"] D --> E["Tidy up afterwards remove unused modules and files, note what works"] E --> A

Backup and Recovery Strategies

Foundry has had built-in backups since Version 11 (build 11.311). On the Setup screen, right-click a world, system or module and choose Take Backup; the backup manager can also Create a Snapshot of every installed package at once. Backups are stored in the Backups folder inside your User Data folder, and Foundry offers to make one before major updates.

Snapshots don't catch everything. Images and sounds you keep outside the worlds, systems and modules folders (for example a shared assets folder in your User Data) are not included. Copy those folders yourself as part of your offsite backup.

Restoring

Restore from the same backup manager on the Setup screen. If you are nervous, first copy the current world folder somewhere safe, so you can go back if the restore doesn't help.

Versions, Channels and Updates

Foundry numbers its software by version (a generation such as V12, V13 or V14) and build (for example 14.368). Builds are released on four channels: Prototype, Development, Testing and Stable. Only Stable builds are recommended for live games; the others are for people who want to test and report bugs.

Moving to a new version is a big step. Modules and game systems often need their own updates first. Before updating, use the Compatibility Preview in the Setup screen's update section to see which of your packages are ready.
Snapshot first. Create a Snapshot before any version upgrade, and keep it until you're sure everything works.
No rush. Staying on the previous version for a few weeks while your modules catch up is perfectly reasonable.
Self-hosting on a server? V14 requires Node.js 24 for the Node.js build. The desktop app includes everything it needs.
Browsers: Chrome, Edge, Firefox and Opera with hardware acceleration enabled. Safari is not supported, so steer Mac players to another browser.

Module Management Best Practices

Modules add the most value and the most risk. Keep them under control:

The Module Hygiene Checklist

Regular Audits

Review installed modules every month or two
Remove modules you no longer use
Check each module's listed compatibility before updating Foundry
Keep a journal page of essential modules and the settings that work
A manager such as Big Bad Module Manager helps with bigger lists (Module Management+ is abandoned and no longer works)

Update Protocol

Take Backup of your world first
Read the module's release notes
Update a few modules at a time, not everything at once
Launch a test world or a copy of your world
Watch the F12 console for red errors
Note any problems and roll back if needed

Performance Monitoring

Notice load times before and after adding a module
Compare how a heavy scene feels with visual modules on and off
Watch for console errors
Ask players how the game runs on their machines

Emergency Procedures

Preventive Maintenance Rhythm

An ounce of prevention is worth a pound of cure. A light routine catches most problems before game night:

flowchart TD A["Before each session launch the world early · check the F12 console · preload the first scene"] --> B["After each session Take Backup of the world · note anything that broke"] B --> C["Every month or two module audit · tidy unused files · test restoring a backup"] C --> D["Before a new Foundry version Compatibility Preview · Create a Snapshot · wait for your key modules"]

Collected Best Practices

Habits Experienced GMs Swear By

Test early in the week: make changes days before the game, not an hour before, so you have time to fix what breaks.
The buddy system: make a trusted player an Assistant GM and show them the basics, so someone can help if you're stuck.
Document what works: a GM-only journal page listing your modules, their settings and anything you changed.
Player tech check: have new players connect once before their first session to sort out browsers and audio.

Five Rules for a Stable Foundry

Back up before you tinker: always, no exceptions.
One change at a time: it makes problems easy to trace.
Read the console: errors usually name the culprit.
Use the community: someone has probably met your problem before.
Story over systems: tech serves the game, not the other way round.

Try It in Foundry

A Disaster Recovery Drill

Practice these when things are calm, ideally in a test world:

Crash recovery (5 minutes):
- Close Foundry while a world is running
- Restart and relaunch the world
- Check that your latest changes are there
The module conflict hunt (10 minutes):
- Relaunch the world with Launch in Safe Configuration and confirm the problem disappears
- Install Find the Culprit! and let it narrow down the module
- Update or disable the culprit and relaunch normally
The backup restore (15 minutes):
- Take Backup of the test world, then delete a journal entry
- Restore the backup from the Setup screen
- Confirm the journal entry is back
The emergency simplification (5 minutes):
- Lower the Performance Mode setting
- Switch to a plain scene with no lights
- Run a few minutes "theater of the mind"

Crisis Scenarios

The Mid-Fight Freeze

Everything locks up during the boss fight. Narrate it ("the wizard's spell twists time itself"), take a five-minute break, relaunch in Safe Configuration to confirm a module is at fault, then disable it and carry on. Hunt down the exact culprit after the session.

The Power Cut

A power failure leaves the world damaged. Because you took a backup after the last session and copied it offsite, you lose a little prep, not years of campaign.

The Struggling Laptop

A new player's older laptop can't keep up with an effect-heavy scene. Lower the Performance Mode setting on that machine and keep a simpler copy of the scene, with fewer lights and no animated tiles, ready to switch to.

Your Troubleshooting Toolkit

Essentials to Bookmark

Browser console: F12, then the Console tab
Safe Configuration: Setup screen, your world's menu, Launch in Safe Configuration
Backups: Setup screen, right-click a package for Take Backup; the backup manager for snapshots and restores
User Data folder: %localappdata%/FoundryVTT on Windows, ~/Library/Application Support/FoundryVTT on macOS, ~/.local/share/FoundryVTT on Linux
Knowledge Base and release notes: foundryvtt.com
Community help: the official Foundry Discord and r/FoundryVTT

Conclusion: Confidence Through Preparation

Every GM meets these problems sooner or later, and almost every one has been solved before. Keep backups current, change one thing at a time, stay on the Stable channel, and know where Safe Configuration and the console live.

Practice the drills when nothing is at stake, and remember that your players care more about the story than about perfect technology. When something does break, you'll have a plan.

Next, if you'd like to play without a group, see Playing Solo in Foundry.