Troubleshooting Tips
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.
Time Zone Data Update
The ZIUpdater tool does not zupport Zulu version 9 and later versions of Zulu.
Azul Repository Tips
embedded
in the package name:
sudo apt-get install zulu-embedded-8
The
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:
-
prefix Java_
-
escaped binary class name (in internal form) which declares the native method
-
underscore separator _
-
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
-
Upgrade to Zulu 11.43 or later version.
-
Make sure the active code page settings match the character set used in pathnames (for more information, see Code Pages).
-
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
- Windows: Observed hang issue with Maven projects launched under Eclipse. See the detailed explanation and workaround for the Eclipse bug. Applies to: all Zulu releases.
- 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
andSSL_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA
.Workaround:
- Open the
$JAVA_HOME/jre/lib/security/java.security
file. - Find the following entry:
security.provider.1=OracleUcrypto security.provider.2=SunPKCS11 ${java.home}/conf/security/sunpkcs11-solaris.cfg security.provider.3=SUN
- Replace the value for security.provider.2:
security.provider.2=SUN
- After the change, the entry should look like this:
security.provider.1=OracleUcrypto security.provider.2=SUN security.provider.3=SUN
- Open the
Support Information
For more information on Zulu, please visit the
- Zulu Installation Guide: http://docs.azul.com/zulu/zuludocs/
- Zulu Community Forum: http://zulu.org/forum/
- Zulu Support: https://www.azul.com/support/