Troubleshooting Common Problems

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:

-Dsun.java2d.opengl=true

-Dsun.java2d.opengl=false

(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

macOS 15.1 introduced a new more restrictive Gatekeeper dialog

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.

Note: macOS 15.1 introduced a more strict Gatekeeper. The old trick of right-clicking VASSAL.app and using Open to bypass Gatekeeper no longer works. You must either use Privacy & Security in System Settings to override Gatekeeper (Open Anyway) and enter an administrator password, or use one of the alternative solutions below.

Alternative solution 1

Download the VASSAL you are interested in the normal way using your web-client. For example VASSAL-3.7.15-macos-universal.dmg.
Mount the dmg file by opening it (double-click) and drag VASSAL.app to your Applications to install it.
Open the Terminal application, find it inside the Utilities folder inside your Applications.
Type: xattr -d com.apple.quarantine /Applications/VASSAL.app and press ENTER to execute the command.
You may Quit Terminal now. The VASSAL application should open normally from the Finder from now onwards.

Alternative solution 2

Use the web-client curl which is part of MacOS. Follow the steps below:

Go to the GitHub Release page

Find the version of VASSAL you are interested in. For example VASSAL-3.6.17-macos-aarch64.dmg for VASSAL version 3.6.17 on Apple M1 chips.
Right click the link and select Copy link address (or similar).

Open a terminal via Finder→Applications→Utilities→Terminal
(If you have not used a terminal before, perhaps this solution is not for you. The terminal is a very powerful tool to interact with the operating system in ways you've never imagined.)
1. In the terminal, change directory to your desktop directory
```
cd Desktop
```
2. In the terminal, type
```
curl -LO <paste copied link> --output vassal.dmg
```
  where <paste copied link> is the link you copied above pasted into the terminal (⌘-V), and press enter.
3. The file will start downloading showing you a nice progress bar
Once downloaded, double-click the VASSAL DMG now on your desktop, and install per usual instructions.

Explanation

MacOS attaches a quarantine attribute to files downloaded by web browsers, which prompts intervention by the Gatekeeper feature. Downloads performed by command line tools like curl and wget do not have this attribute set.

(Windows) Browsers give a "this file isn't commonly downloaded" warning when downloading installer

Edge warns about the installer download--start by choosing "Keep".

On the repeated warning, choose Keep anyway to save the download

In Chrome, choose Keep to save the download from the warning dialog

When downloading a newly-released version of VASSAL with Edge, Chrome, and other browsers, Microsoft SmartScreen may intervene with a warning that the file isn't commonly downloaded. Respond to these prompts by choosing to keep the file anyway.

(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.

Antivirus scanner quarantines the installer

AVG "Threat secured" dialog

SHA256 hashes are published with each release

Some antivirus scanners (AVG and Avast in particular) mistdetect Vassal's Windows installers as a threat. The way to fix this problem, both for yourself and for others, is to report the false positives to your AV vendor. (E.g., there is a "Report as false positive" link in the screenshot from AVG shown here.)

If you want to verify that your installer is the installer we released, you can check the SHA256 hash of your installer file against the list we publish. (If you need a tool for computing the SHA256 hash of the installer file you have, a simple solution is to try uploading the file to VirusTotal, which will compute the file's SHA256 hash and display it.)