Troubleshooting Common Problems

From Vassal

Here are some common technical problems players encounter with VASSAL, and how to troubleshoot them.

Nothing Happens When I Open Vassal

Are you running some antivirus software? We've had some reports of AV software swiping files VASSAL needs to run.

In particular, please check the jre\bin directory under the directory in which VASSAL is installed. Do you see files called javaw and java there? (Or, if your file browser isn't hiding extensions for known file types, javaw.exe and java.exe?) If those files are missing it means that your anti-virus software has blocked or quarantined the bundled Java JVM that VASSAL uses to run. Open your Anti-Virus program and white list those files.

Beginning with VASSAL 3.3.0, Java is "bundled" with VASSAL on Windows and Mac (not on Linux). This means that on those platforms it no longer matters what version of VASSAL you have installed - indeed you don't have to separately install Java any more on Windows and Mac. However, some antivirus software does not trust the Java JVM executables which we provide. Thus it must be told to allow them.

Another possible cause if Vassal worked before but has stopped opening is that you have a corrupted global preferences file. Look for the file prefs/V_Global (the prefs directory is in the same directory as the Error Logs) , move it somewhere else, and try to start Vassal.

(Windows) "Tearing" on maps, Corrupted Graphics, or Map Not Fully Updating

Map Tearing Example
Fix for Map Tearing

If you run on Microsoft Windows and your map is not updating correctly (e.g. "tearing" or not fully updating), go to Vassal's preferences and check the box for Disable DirectX D3D Pipeline.

Some combinations of video drivers and versions of Java don't work well together. If you have rendering problems with Direct3D turned on and they go away when you turn it off, then you have one of those bad combinations. This preference (and potential problem) exists only on Windows machines.

(All Platforms) "Tearing" on maps, Corrupted Graphics, or Map Not Fully Updating

If you are having tearing on maps, and are not running on Windows (or if you have already tried the Windows-specific solution above):

After the first time you run one of these builds, there will be a file called vassal.vmoptions in VASSAL's config directory where you can add VM flags for the Player, one per line.

Linux: ~/.VASSAL/vassal.vmoptions
Mac OS X: ~/Library/Application Support/VASSAL/vassal.vmoptions
Windows: C:\Users\<username>\AppData\Roaming\VASSAL\vassal.vmoptions

Try these two lines, in order, one at a time:



(Mac) "VASSAL cannot be opened because the developer cannot be verified. MacOS cannot verify that this app is free from malware."

Example of Mac Gatekeeper blocking VASSAL (Click Okay)
Step 1: System Preferences -> Security & Privacy
Step 2: Unlock (if needed) and click Open Anyway
Step 3: Click Open

If you have the current or a recent version of MacOS, Gatekeeper is probably active--MacOS will block VASSAL from running on the first attempt (because this isn't what Apple considers a code-signed app).

You'll have to go into System Preferences -> Security & Privacy to allow it to run. This only needs to be done once.

Alternatively you can open a Finder window, type VASSAL into the search field, and double click on your new VASSAL install to open it for the first time - this will give you an "are you sure?" type dialog, and once you are past that then you will be able to open VASSAL normally in the future.

(Windows) "Windows protected your PC" when running the installer

Microsoft Defender SmartScreen prevented an unrecognized app from starting. Running this app might put your PC at risk.
Click the Run anyway button to continue

Windows Defender sometimes blocks VASSAL's installer from running: "Microsoft Defender SmartScreen prevented an unrecognized app from starting. Running this app might put your PC at risk."

Windows checks whether executables downloaded from the internet are signed and how often they've been downloaded (globally). Our installer is not presently signed, so you may see this message if you try installing VASSAL shortly after a new release. It does not indicate a problem with the installer.

Click More info in the dialog to reveal the Run anyway button to run the installer.