Troubleshooting Tips

The Azul Community site contains a running list of recent tips. The following is a brief list of common trouble points:

Preparation Tips

Ensure your PATH and JAVA_HOME variables are set accurately in the shell or context of your runtime application. Crosstalk with other installed JVMs leads to aberrant, often random unwanted behaviors.

Ensure you have the proper Zulu architecture for your OS and kernel. Using incorrect processor type or bitness may fail to operate at all.

VM Property Override

Some applications may expect particular VM property string values, such as vendor, set to values different from OpenJDK defaults. Zulu provides the XX:+OverrideVMProperties argument to allow new property values. Use -XX:+OverrideVMProperties with a -D option for the property to be overridden. For example:

-XX:+OverrideVMProperties -Djava.vm.vendor="CompanyName"

JRE-only Tips

Zulu builds are generally visible to monitoring tools by default. In JRE-only Zulu builds, Java may be invisible to monitoring tools. This is due to the -XX:-UsePerfData flag default setting to off for JRE-only builds.

To resolve this issue, run the target JRE with -XX:+UsePerfData. This enables monitoring tools to see the Java instance.

Tomcat Advisory

To avoid unexpected failures of Zulu 8, it is recommended to upgrade your Tomcat 6 to the version 6.0.37 or higher, and Tomcat 7 to the version 7.0.34 or higher.

Cassandra Issue

Cassandra 3.7 cannot start with Zulu 8.27 because of the known dependencies on some JDK internal classes and interfaces that have been changed in Java SE 8, update 162. See CASSANDRA-14173.

Azul Repository Tips

Azul provides many Linux binaries on the Azul Repository. They remain predominantly compatible for x86-64. To install Arm packages from the repository using APT, run the following command with the term embedded in the package name:

sudo apt-get install zulu-embedded-8

The Azul repository can determine whether your Arm processor is hard-float or soft-float, and whether it is 32-bit or 64-bit.

Notice how this differs from the command for x86-64 which omits embedded in the package name:

sudo apt-get install zulu-8

All other APT commands are applicable to all platforms. Review Installation on Linux Using an APT Repository for more on installing Zulu through APT.

New mapping rules from a Java native method name to a C native library implementation function name

The mapping produces a native method name by concatenating the following components derived from a native method declaration:

  1. prefix Java_

  2. escaped binary class name (in internal form) which declares the native method

  3. underscore separator _

  4. escaped method name

Note:

Overloaded native method names, in addition to the above components, have an extra two underscore separators __ appended to the escaped parameter descriptor (JVMS 4.3.3) of the method declaration.

The escaping process leaves every alphanumeric ASCII character (A-Za-z0-9) unchanged and replaces each UTF-16 code unit with the corresponding escape sequence, see the table below.

Character UTF-16 code unit Escape sequence
Forward slash /

U+002F

_

Unicode character, representing characters other than ASCII alphanumeric ([A-Za-z0-9]), forward slash, underscore, semicolon or left square bracket. U+WXYZ

_0wxyz*
Underscore _

U+005F

_1
Semicolon ;

U+003B

_2
Left square bracket [

U+005B

_3

* where w, x, y, and z are the lower-case forms of the hexadecimal digits W, X, Y, and Z. For example, U+ABCD becomes _0abcd.

Note:

Since names of classes and methods in Java source code never begin with a number, we can use _0, ..., _9 for escape sequences. However, that is not the case for class files that were not generated from Java source code.

If the native name to be escaped contains a surrogate pair, then the high-surrogate code unit and the low-surrogate code unit are processed separately. The escaping process result is a name string consisting of only ASCII characters A-Za-z0-9 and underscores.

To preserve one-to-one mapping to a native method name, the VM makes the following extra check:

If after the escape processing of any string (class or method name, or argument type) from the native method declaration, we have in the result an unchanged "0", "1", "2", or "3" character standing at the beginning of the escaped string, or immediately after an underscore separator, then the escaping process is considered as "failed." In this case, no further search of the native library is performed, and the attempt to link the native method invocation throws UnsatisfiedLinkError.

To avoid legacy compatibility issue, skip the extra check by setting the UseLegacyJNINameEscaping flag.

Creating a Symlink to the jvm-exports Directory

While installing Zulu on RPM systems, the installer adds it to the /usr/lib/jvm/zulu-8/ directory. Certain tools, such as ant expects Java executable to be present from the following location /usr/lib/jvm-exports. To avoid error messages, you need to create a symlink to the jvm-exports directory after Zulu installation. For example, assume that Zulu is installed in /usr/lib/jvm/zulu-8-x86. Perform the following steps to create a symlink:

cd /usr/lib/jvm-exports

ln -s /usr/lib/jvm/zulu-8-x86 zulu-8-x86

To verify the symlink, run:

ls -lart | grep -i "zulu-8-x86"

You should expect the following output:

0 lrwxrwxrwx 1 root root 34 Sep 29 18:22 zulu-8-x86 -> /usr/lib/jvm/zulu-8-x86

Running Java Flight Recording in Zulu 8

Zulu 8 inherits the implementation of Java Flight Recorder (JFR) from OpenJDK 11.

To use JFR on an active Zulu java process no command-line option is necessary, just run jcmd JAVAPID JFR.start to enable recording when needed. The overhead of JFR before it gets activated with JFR.start is negligible since none of the events get sent and no JFR java classes get loaded (JFR java classes undergo class transformation during the load time). Alternatively, you can enable recording directly on the launch of the Java process by adding and configuring -XX:StartFlightRecording. Setting -XX:-FlightRecorder on the command line prevents JFR from being enabled during runtime. It gives absolutely no performance benefit.

CKR_SAVED_STATE_INVALID exception on Solaris 10

Zulu 8 might throw CKR_SAVED_STATE_INVALID exception due to issues in Solaris 10 (see JDK-2209405).

Workaround

Disable broken mechanisms by updating the configuration file $JAVA_HOME/jre/lib/security/sunpkcs11-solaris.cfg and including the following entries into the list of disabled mechanisms:

CKM_SHA256 CKM_SHA384 CKM_SHA512

Problem with running Java on Windows 10 when JAVA_HOME contains Non-ASCII characters

Early versions of Zulu 11 may have issues with Java startup when JAVA_HOME path contains non-ASCII characters.

Workaround

  1. Upgrade to Zulu 11.43 or later version.

  2. Make sure the active code page settings match the character set used in pathnames (for more information, see Code Pages).

  3. Make sure the Windows default language selection for non-Unicode programs match the character set used in pathnames (for Windows 10, go to Control Panel > Region > Administrative > Language for non-Unicode programs). If the problem persists, ensure that you have not checked the beta option Use Unicode UTF-8 for worldwide language support.

Open Product Issues

  • Zulu RPM Installers on SLES 11.3: Using the Zulu .rpm installer on a SLES 11.3 system requires RPM version 4.8 or later. Workaround: Use the Zulu .zip installer or upgrade your RPM to 4.8 or later.

  • Zulu 8.14, 7.16, and 6.14 cannot be downgraded to the earlier versions by using an RPM package.

    Workaround: Uninstall Zulu 8.14, 7.16, or 6.14 and then install an earlier version of Zulu.

  • CoreOS: CoreOS cannot transfer zero-length packets using datagram sockets. See more details in https://github.com/coreos/bugs/issues/1834.
    Workaround: Upgrade CoreOS to the kernel version 4.9.9 or higher.

  • OpenJSSE: The following algorithms are not supported by default by Zulu11.41 on Solaris 11.4: SSL_RSA_EXPORT_WITH_DES40_CBC_SHA and SSL_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA.

    Workaround:

    1. Open the $JAVA_HOME/jre/lib/security/java.security file.
    2. Find the following entry:

      security.provider.1=OracleUcrypto security.provider.2=SunPKCS11 ${java.home}/conf/security/sunpkcs11-solaris.cfg security.provider.3=SUN

    3. Replace the value for security.provider.2:

      security.provider.2=SUN

    4. After the change, the entry should look like this:

      security.provider.1=OracleUcrypto security.provider.2=SUN security.provider.3=SUN

Support Information

For more information on Zulu, please refer to the following resources available on the Azul website: