Overview
This article covers various causes for Foundry VTT displaying your scene as a black or gray box. In many cases, gray or black screens can be fixed with just a few short steps. Not all of the steps listed here apply in all cases. Determine the most likely cause from the options below and begin there.
Before You Begin
The most common reasons for a black screen in Foundry VTT are module conflicts and extremely large background images. Gray screens usually result from hardware acceleration, low hard drive space, and network issues. Given the wealth of options Foundry VTT offers for lighting and vision, it's also possible that a black screen results from a misconfigured Scene or Token. Fortunately this is quick and easy to check for.
Scene and Token Settings
Scenes and tokens have several settings that work together to display the scene to the player. Start by checking the following:
- Scene Settings: Check that the Scene is not zoomed into a black part of the map. If 'Token Vision' is checked in the Scene's Lighting section and 'Global Illumination' is unchecked, tokens will need Lights, or have values set for their vision.
- Scene Background: If a Scene's background color is set to black and the image fails to load for one of the reasons in the following Gray Screen section, it will appear to be a black box. To rule this out, open the Scene Configuration window, and set the field for 'Background Color' to a color other than black. If the Scene no longer shows a black box, continue to the Gray Screen section of this article.
- Token Settings: Check that 'Has Vision' is checked under the token's Vision tab. If no Lights are on the scene, tokens with vision need their Dim or Bright vision set to numbers above zero in order to see.
The Scenes and Tokens contain more information on these and other Scene and Token settings.
Foundry VTT Shows a Black Screen
Module Errors
Out of date modules or module conflicts can cause a Scene to display a black box instead of loading properly. The fastest way to check this and begin finding the module at fault is to launch your world in Safe Configuration. The article Launch a Foundry Virtual Tabletop World in Safe Configuration explains how.
Background Image Dimensions Are Very High
While Foundry VTT can scale up an image to arbitrarily large sizes, the original size of the image in pixels has a hard limit. If the image used is too wide or too high for your hradware to render, a black screen will result. Usually this limit is around 8,000 pixels in either dimension for older PCs and 16,000 pixels for newer PCs. If you're creating your own maps, consider scaling them down or exporting at a lower resolution, such as 100 pixels per grid square if using a grid. The Content Creation Style Guide contains more information under "Scenes - Resolution and Uniformity."
Foundry VTT Shows a Gray Screen
As mentioned above, gray screens usually result from technical issues. The most common of these is Hardware Acceleration being disabled. An incorrect or invalid image path, lack of hard drive space, or network complications can also result in gray screens.
A Warning Related to Hardware Acceleration Appeared
Foundry VTT requires Hardware Acceleration to run properly and smoothly. If this is disabled, you may get a black or gray screen. Enabling Hardware Acceleration usually resolves this.
Use the relevant set of steps to enable Hardware Acceleration in your browser or the standalone Foundry application. If you're using Windows, you may need to use the last set of steps to prevent Windows from overriding Hardware Acceleration settings.
- Open Chrome and enter
chrome://settingsin the location bar at the top of the screen. - Click on System on the menu on the left.
- Enable Use hardware acceleration when available.
- Enter
chrome://flagsin the location bar. - Enable Override software rendering list.
- Close out of all Chrome windows and relaunch Chrome.
- Open Firefox and enter
about:config. If a warning page shows, click Accept the Risk and Continue. Enabling Hardware Acceleration for Foundry VTT will not compromise your security. - Search for
layers.acceleration.force-enabledin the top search bar - Click the two arrows on the right hand side. The bottom of the search results should say True
- Close out of all Firefox windows and relaunch Firefox.
- MacOS: Open a terminal and enter
open -a FoundryVTT --args ignore-gpu-blocklist - Linux: Open a terminal in your Foundry VTT installation directory and enter
./foundryvtt --ignore-gpu-blocklist
Enabling Hardware Acceleration in Windows requires several steps. They are detailed below
- Navigate to to your Foundry installation folder.
- Right click on 'foundryvtt.exe', and click 'Create Shortcut.'
- click the shortcut and select 'Properties.'
- In the 'Target' field, add a space and enter
--ignore-gpu-blocklist. The field should look similar to"C:\...\FoundryVTT.exe" --ignore-gpu-blocklist, where "..." is the path to your Foundry VTT installation folder. Note that the addition is outside of the quotes. - Press 'OK', and then use this shortcut to launch Foundry VTT from now on.
If Foundry VTT still warns that Hardware Acceleration is disabled, Windows may be overriding your browser's settings. This usually happens on notebook PCs with a dedicated GPU. The following steps explain how to check for and correct this.
- Press your Windows key, type "Settings", and press 'Enter.'
- Click on 'Display' on the lefthand side, then scroll down and click on 'Graphics Settings.'
- Select "Classic App" from the drop down menu.
- Click 'Browse', then find and select your browser or Foundry Virtual Tabletop executable
- Click the 'Options' button and select the appropriate GPU. Typically this is the "High Performance" option.
- Click 'Save.'
Missing Background Image or Bad Path
If your background image has been renamed or moved, Foundry VTT will display a gray screen or simply the Scene Background Color in place of the scene. To resolve this, check that the Background Image path in the Scene's is correct and that the file exists on your file system.
Low Hard Drive Space
If you have less than 4 GB of free space on your boot drive (C drive for Windows users), Chromium based browsers such as Chrome, Edge, or the one used in the standalone Foundry VTT application, will not load and store images properly. This is accompanied with an error message in the developer console that includes the words "Failed to fetch." Freeing up more than 4 GB of space on your boot drive will resolve this.
Network Issues
Network problems between the host server and users are another cause of gray screens. Slow internet speeds, poor quality connections, or even problems with a user or host's internet service provider can lead to gray screens. Reducing how much data needs to be transferred to players by following the Media Optimization Guide is sometimes enough to resolve this issue. If you're self hosting and your internet upload speed is less than 12 Mbps, consider using a free or premium hosting solution. Details can be found in the Hosting Options Guide.