Troubleshooting

This page covers common Local VTT problems and what to check first.

Most issues come down to one of four things:

• The wrong scene is shown in Player View.
• A layer or item is hidden.
• Fog of war is hiding something.
• A campaign asset was moved, renamed, or deleted outside Local VTT.

Use this page as a symptom index:

• Player View: wrong display, waiting screen, black screen, missing scene.
• Visibility: players see too much, players cannot see expected content, missing tokens.
• Assets: missing token images, missing map images, missing video files, stale recent campaigns.
• Grid And Measurement: grid alignment, measurement, snapping, fog reveal shape issues.
• Performance And Media: video playback, animated maps, effects performance.
• Dice And Turn Order: Player View dice output, delayed 3D results, missing turn indicators.
• Install And Startup: Windows installer warnings, app startup problems.

[insert image]

Player View Opens On The Wrong Display

If Player View opens on the wrong screen:

1. Exit fullscreen if needed.
2. Drag the Player View window to the correct display.
3. Open Player View Setup.
4. Confirm the preferred display.
5. Save the setting.
6. Reopen Player View if needed.

If the preferred display is disconnected, Local VTT opens Player View normally so you can move it manually.

Player View Does Not Show The Scene

If Player View is open but does not show the expected scene:

1. Confirm the scene was sent to Player View.
2. Check whether Player View is showing the waiting screen.
3. Check whether Hold or Blackout mode is active.
4. Confirm the scene still exists.
5. Confirm Player View is not on a different display or hidden behind another window.
6. Send the scene to Player View again.

Opening a scene in GM View does not always mean it has been shown to players.

Player View Shows A Waiting Screen

The waiting screen can appear when:

• Player View has been opened before a scene is sent.
• The shown scene was deleted.
• The shown scene is unavailable.
• The GM cleared, held, or changed the player display state.

To fix it, send an available scene to Player View.

[insert image]

Player View Is Black

If Player View is black:

1. Check whether Blackout mode is active.
2. Exit fullscreen and confirm the window is responsive.
3. Send the scene to Player View again.
4. Check display connection and monitor settings.
5. Close and reopen Player View if needed.

If the app is still responsive in GM View, the issue is usually display state or Player View mode.

Players See Something They Should Not

If players can see hidden content:

1. Use Hold or Blackout if you need to hide the display quickly.
2. Check the active scene in Player View.
3. Check item Player View visibility.
4. Check layer visibility.
5. Check fog of war.
6. Check whether a reveal shape exposes the area.
7. Check whether the wrong scene was sent to Player View.

Common causes include player-visible tokens, visible drawings, visible templates, visible effects, or fog shapes revealing more than intended.

Players Cannot See Something They Should See

If players cannot see expected content:

1. Confirm the correct scene is shown in Player View.
2. Check Player View is not in Hold, Blackout, or waiting screen mode.
3. Check the relevant layer visibility.
4. Check the item's Player View visibility.
5. Check fog of war.
6. Confirm the item is inside a revealed area if fog is active.
7. Save and resend the scene if needed.

[insert image]

A Token Is Missing From Player View

If a token does not appear to players:

1. Confirm the token exists in the active scene.
2. Check the token's Player View visibility.
3. Check the Tokens layer visibility.
4. Check fog of war.
5. Confirm the token overlaps a revealed area.
6. Confirm the correct scene is shown in Player View.

In hidden or partially hidden fog modes, player-visible tokens can still be hidden if they are outside revealed fog.

A Token Image Is Missing

If a token appears broken or its image is missing:

1. Check whether the campaign folder was moved or copied completely.
2. Confirm the token image still exists in assets/tokens/.
3. Restore the missing image from a full campaign backup if available.
4. Avoid renaming or deleting files inside assets/tokens/ outside Local VTT.

Metadata backups do not include token image files.

A Map Image Or Video Is Missing

If a scene map is missing:

1. Confirm the campaign folder still contains the map file in assets/maps/.
2. Check whether the campaign was only partially copied.
3. Restore the missing map from a full campaign backup if available.
4. Reimport the map if needed.

Scene JSON backups can restore map references, but they cannot restore deleted map files.

Scene Or Token Thumbnail Looks Wrong

If a scene thumbnail or token preview is missing, stale, or no longer matches the asset, use Regenerate Thumbnails from the Campaign panel.

If regeneration reports failed assets, confirm the source map, video, or token files still exist in the campaign folder and can be opened by the system.

Recent Campaign Does Not Open

If a recent campaign cannot be opened:

1. Check whether the campaign folder was moved, renamed, or deleted.
2. Use Open Campaign to select the folder in its new location.
3. Remove stale recent entries if the folder no longer exists.

Recent campaigns are shortcuts to local folders. They do not contain the campaign data themselves.

Save Indicators Do Not Clear

If the app still shows unsaved changes:

1. Save the active scene.
2. Save campaign changes.
3. Check whether both campaign and scene changes are pending.
4. Confirm there are no open modals with unapplied changes.

Campaign changes and scene changes are tracked separately.

Backup Recovery Did Not Work

If Restore Revision or manual recovery did not restore what you expected:

1. If using Restore Revision, confirm you selected the intended campaign or scene backup.
2. If replacing files manually, confirm Local VTT was closed before replacing files.
3. Confirm you restored the correct backup file.
4. Confirm campaign backups were copied over campaign.json.
5. Confirm scene backups were copied over the matching file in scenes/.
6. Confirm required asset files still exist.

Backups restore metadata only. They do not restore maps, token images, videos, or thumbnails.

Grid Does Not Line Up With The Map

If the grid does not align:

1. Check the scene grid mode.
2. Check the map fit mode.
3. Enter known map grid dimensions if available.
4. Use the Map Calibration Assistant.
5. Check whether the map image includes borders, margins, or labels.
6. Save the scene after calibration.

[insert image]

Measurement Looks Wrong

If ruler, movement, or template measurement looks wrong:

1. Check the scene grid mode.
2. Check measurement settings.
3. Confirm the map grid is calibrated.
4. Confirm snapping behavior.
5. Check whether the scene is square, hex, or gridless.

Measurement depends on scene configuration.

Snapping Does Not Work As Expected

If snapping feels wrong:

1. Check whether the active tool supports snapping.
2. Hold Ctrl or Cmd while placing, drawing, or measuring where supported.
3. Confirm the scene has a square or hex grid.
4. Check grid calibration.
5. Try zooming in for more precise placement.

Fog Of War Reveals Too Much

If fog reveals more than intended:

1. Check the fog mode.
2. Check Player fog opacity.
3. Check reveal shape placement.
4. Check fog shape order.
5. Check whether a large reveal shape overlaps the area.
6. Hide, reorder, edit, or delete the problem fog shape.

Fog Of War Hides Too Much

If players cannot see enough of the map:

1. Confirm the area has a player-visible reveal shape.
2. Check whether a hide shape covers the area.
3. Check fog shape order.
4. Check Player fog opacity.
5. Confirm the correct scene is shown in Player View.

Video Map Does Not Play Correctly

If a video map does not play as expected:

1. Confirm the file is MP4 or WebM.
2. Check whether video playback is paused.
3. Try toggling playback controls.
4. Confirm the video file still exists in assets/maps/.
5. Try reimporting the video.
6. Test the scene before running it live.

Large or unusual video files may behave differently depending on system support.

Animated Maps Or Effects Feel Slow

If performance drops:

1. Reduce active animated effects.
2. Lower weather intensity or opacity.
3. Avoid stacking video maps with many effects.
4. Close unused apps on the computer.
5. Test large maps before the session.
6. Use static maps for critical encounters if needed.

Dice Results Do Not Show In Player View

If players cannot see dice results:

1. Check dice display settings.
2. Confirm Player View output is enabled for the roll mode.
3. Confirm Player View is open.
4. Check whether Player View is in Hold, Blackout, or waiting screen mode.
5. Use text results for quick testing.

3D Dice Result Seems Delayed

3D dice may wait for the roll to settle before showing the final result.

If you need a faster roll:

• Use text result mode.
• Use a 3D Panel instead of a 3D Scene Roll.
• Check recent roll history for the final result.

Turn Order Does Not Show In Player View

If Turn Order is missing from Player View:

1. Confirm Turn Order is active or playing.
2. Check Player View turn indicator settings.
3. Confirm Player View is showing the correct scene.
4. Check visible-entry limits.
5. Check indicator placement and sizing.

Installer Shows A Windows Warning

The Windows installer is not currently code signed.

Windows may show a publisher or SmartScreen warning.

This does not necessarily mean the installer is broken. It means Windows cannot verify a signed publisher for the app.

Only install builds from a trusted source.

[insert image]

Development Install Problems

If you are building Local VTT from source and run into npm install, Electron binary, or Linux graphics startup issues, see Development And Contributing.

App Will Not Start

If Local VTT will not start:

1. Try launching it again.
2. Restart the computer.
3. Reinstall the latest release.
4. Confirm antivirus or system security is not blocking the app.
5. If using a development build, run the local verification commands from the development guide.

When In Doubt

For most display or visibility problems, check in this order:

1. Is the correct scene open in GM View?
2. Was the correct scene sent to Player View?
3. Is Player View in Hold, Blackout, or waiting mode?
4. Is the relevant layer visible?
5. Is the item visible to players?
6. Is fog of war hiding it?
7. Are required asset files still inside the campaign folder?

Related Pages

• Player View Setup
• Campaigns And Backups
• Scenes And Maps
• Maps, Grid, And Calibration
• Fog Of War
• Tokens And Token Library
• Visibility Rules