Wiki - FAQ


  1. General Questions
  2. Minimum Requirements
  3. Known Issues
  4. Troubleshooting



Suppressing Warnings

QZ Tray Cost

Installing New Version

Browser Managed By Organization

Question: Does QZ Tray make changes to the browser?

Yes. For normal QZ Tray operations a few, small changes are needed, please see below:

Minimum System Requirements

Java Versions

Product Minimum Version
QZ Tray 2.2 OpenJDK 11 (bundled)
QZ Tray 2.1 Java 8 / OpenJDK 1.8*
QZ Tray 2.0 Java 7 / OpenJDK 1.7*
QZ Tray 1.9 Java 7 / OpenJDK 1.7
QZ Print 1.9 Java 6 / OpenJDK 1.6

*HTML printing in QZ Tray 2.x requires Java 8 + Java FX.

Operating Systems

Operating System Minimum Version
Apple OS X OS X 10.7 Lion or higher*
Microsoft Windows Windows XP or higher*
Linux Ubuntu 12.04 Precise or higher

Version 2.0 or higher requires 512MB of free memory (RAM), recommends 6GB or higher total system memory for raster graphics.

*Safari 5.1.7 is bundled with Lion but is not supported. Alternate browser required.
*Windows XP requires manual certificate installation. Will prompt at install time.

Web Browsers

Web Browser Minimum Version
Safari Safari 6.0.3 or higher
Firefox Firefox 31 or higher*
Chrome Chrome 31 or higher
Internet Explorer IE 10 or higher*
Microsoft Edge 20.x or higher*

* Firefox requires a browser restart for HTTPS
* IE/Edge on domain networks require external DNS access to due to a Local Intranet Limitation.

Known Issues

Conflicting Applications

The following applications may cause issues with QZ Tray installation.


Debugging QZ Tray

Console Logs
PKIX Build Path Failed

Sometimes a message java.lang.UnsupportedOperationException: Cannot parse (FILE) will appear. This is often a failure by Java to download the specific resource and it will be followed by Caused by: PKIX path building failed

Crash During Printing

Cannot Launch Software

  1. A corrupt Java installation may prevent the software from installing or loading. A corrupt Java installation is fairly common in Windows, and can be resolved by reinstalling Java using the Java offline installer. The offline installer has been reported to fix many issues with corrupt Java installations. Take a look at this guide for our recommended steps on reinstalling Java on all platforms.

    Signs of a corrupt Java install:

    Creating keystore for ws://localhost...
    - [failed] Creating a CA keypair...

    ... or ...

    java -version
    "An error has occurred while processing the shared archive file. Unable to unmap shared space. Error occurred during initialization of VM. Unable to use shared archive."

  2. Sometimes custom JAVA_HOME environmental variables will prevent QZ Tray from loading. If the software can be launched via the command line this is likely the case. In windows this can be checked by going to System > Advanced system settings > Environment Variables

  3. HTML printing (JavaFX) can cause printing to fail if the following is true:

    • Issue: HTML page width is set to 100%.
      Remedy: Hard-code an acceptable page with using CSS, e.g. 800px
    • Issue: Printer resolution for HTML print is high (e.g. 600dpi, 1200dpi).
      Remedy: Hard-code a lower DPI (e.g. 300dpi) using { units: 'in', density: 300 }. We also recommend setting a sane fallbackDensity incase 300dpi is unsupported by certain hardware.
    • Issue: Out of memory issues can occur if running the 32-bit JVM.
      Remedy: See 32-bit vs. 64-bit: section below.
    • Issue: java.lang.NoClassDefFoundError: javafx/print/PrintColor at qz.printer.PrintOptions$ColorType
      Remedy: JavaFX is not distributed with all Java versions. Please install JavaFX for your platform (e.g. openjfx, etc).
  4. Images/PDFs cause software to stop working: More commonly Cannot call method public void, this is generally a sign that the JVM has hit an unrecoverable error. The most common cause is large print operations on a 32-bit JVM. A temporary workaround is to specify { rasterize: false } in the configuration, but this will only fix PDFs. A permanent solution is to switch to a 64-bit JVM which allocates a larger heap space. If 32-bit is required, additional heap space may be allocated via command-line.

  5. 32-bit vs. 64-bit: Some 64-bit workstations have both 32-bit and 64-bit Java versions installed. If both are needed, make sure both are upgraded, otherwise, removing the 32-bit version is advised to assist with the troubleshooting process.

  6. Insufficient Java Version "A Java Exception has occurred" may appear if attempting to launch against an outdated Java version. For a list of minimum Java requirements see Java Versions. May also be reported as Could not find the main class Program will exit.

  7. Disk Corrupted: Always try fsck (Linux), Disk Utility (MacOS) or chkdsk (Windows). Physical drives can show strange symptoms when they are beginning to fail however SSDs hard drives are susceptible to a condition called "worn bits" or more properly "SSD Endurance" which is responsible for re-using NAND flash memory. This process should be self-healing but on occasion can cause issues with certain drive firmwares. Make sure to scan your disk for health when encountering launch issues.

Cannot List Printers

  1. Mac

    Due to an upstream bug with Java, printer listings may fail on Mac.

    The current workaround is to:

    • Open System Preferences
    • Printers and Scanners
    • Right Click > Reset Printing System
    • Re-add all printers

    We realize this is not ideal, but have found no another work-around on Mac.

  2. Windows

    Although rare, there are scenarios of not being able to list printers, only being able to list one printer, or listing printers takes several minutes to complete. This is likely caused by a driver conflict between the offending printer driver and the print spooler, resulting in the entire print subsystem to hang.

    The workaround is to remove the offending printer or printer driver.

Raw Printer Queues

If your thermal or label printer has undesired results, it may be improperly configured. Here are our tutorials for setting up a printer to receive raw languages on each platform:

Note: Some Windows drivers, such as Zebra's ZDesigner driver for Microsoft Windows, will support raw printing alongside pixel-based/PostScript printing. You may use those drivers or a raw-generic/text-only driver to send raw commands, but the generic driver will not be able to print images/PDF/HTML.

Debugging WebSockets

By default, QZ Tray suppresses verbose websocket information from the console, however occasionally this information may be useful for debugging/troubleshooting connectivity issues.

Debugging WebSockets in 2.0
Debugging WebSockets in 1.9

Socket Disconnected

Other Errors

Invalid JSON


Azure Fingerprint Setting
  1. Within the Azure web app, in the section Settings, TLS/SSL Settings, Private Key Certificates, Import
    • Upload the .pfx and type the password.
  2. Within the web app, in the Settings, Configuration, Application Settings, New Application Setting
  3. Adjust the code, replacing "<fingerprint>" with the certificate fingerprint.
    -	var KEY = "private-key.pfx";
    -	var PASS = "S3cur3P@ssw0rd";
    -	var cert = new X509Certificate2( KEY, PASS, X509KeyStorageFlags.MachineKeySet | X509KeyStorageFlags.PersistKeySet | X509KeyStorageFlags.Exportable );
    +	X509Store certStore = new X509Store(StoreName.My, StoreLocation.CurrentUser);
    +	certStore.Open(OpenFlags.ReadOnly);
    +	X509Certificate2Collection certs= certStore.Certificates.Find(X509FindType.FindByThumbprint, "<fingerprint >", false);
    +	// Get the first cert with the fingerprint
    +	if (certs.Count > 0)
    +	{
    		X509Certificate2 cert = certs[0];
    		RSACryptoServiceProvider cspStrong = (RSACryptoServiceProvider)cert.PrivateKey;
    		byte[] data = new ASCIIEncoding().GetBytes(request);
    		byte[] hash = new SHA1Managed().ComputeHash(data);
    		Response.ContentType = "text/plain";
    		Response.Write(Convert.ToBase64String(cspStrong.SignHash(hash, CryptoConfig.MapNameToOID("SHA512"))));
    +      }
  4. These Azure steps will need to be reproduced each time the certificate is replaced or renewed.

Cloudfront Cache Settings

Keyset Does Not Exist

If the .NET signing example fails on a load balanced server, please try one of the following:

IIS User Profile Setting
  1. Change the setting which toggles the user profile for the application pool identity user. When set to false, the key containers aren't accessible:
Edit this page