17 Submit a Bug Report

This chapter shows you how to submit a bug report. It includes suggestions about what to try before submitting a report and which data to collect for the report.

This chapter contains the following sections:

• Check for Fixes in Update Releases

• Prepare to Submit a Bug Report

• Collect Data for a Bug Report

• Report a Bug

• Collect Core Dumps

Check for Fixes in Update Releases

Regularly scheduled updates to each release contain fixes for a set of critical bugs identified since the initial release of the platform.

When an update release becomes available, it becomes the default download at the Java SE Downloads page.

The download site includes a link to the release notes that list the bug fixes in the release. Each bug in the list is linked to the bug description in the bug database. The release notes also includes the list of fixes in previous update releases. If you encounter an issue, or suspect a bug, then, as an early step in the diagnosis, check the list of fixes that are available in the most recent update release.

Sometimes, it is not obvious if an issue is a duplicate of a bug that was already fixed.

Prepare to Submit a Bug Report

The following is the recommended procedure to submit a bug report.

Before submitting a bug report, consider the following recommendations:

• Collect as much relevant data as possible. For example, generate a thread dump in the case of a deadlock, or locate the core file (where applicable) and hs_err file in the case of a crash. In every case, it is important to document the environment and the actions performed just before the problem happened. See Collect Data for a Bug Report.
• Where applicable, try to restore the original state and reproduce the problem using the documented steps. This helps to determine if the problem is reproducible or an intermittent issue.
• If the issue is reproducible, try to narrow down the problem. In some cases, a bug can be demonstrated with a small standalone test case. Bugs that are demonstrated by small test cases will typically be easy to diagnose as compared to test cases that consist of a large complex application.
• Search the Java Bug Database to see if this issue or a similar issue was reported. If the issue has already been reported, then the bug report might have further information, such as the following:

  • If the issue was already fixed, then the release in which it was fixed is given.

  • A workaround for the issue.

  • Comments in the evaluation that explain, in further detail, the circumstances that cause the issue to happen.

• If you conclude that the issue was not already reported, then report it at Report a Bug or Request a Feature.

Before reporting an issue, verify that the environment where the problem happens is a supported configuration. See Oracle JDK 22 Certified System Configurations.

In addition to the system configurations, check the list of supported locales. See JDK 22 Supported Locales.

Collect Data for a Bug Report

The following sections list the commands or recommend a general procedure to obtain the data:

• Detailed Description of the Problem

• Hardware Details

• Operating System Details

• Java SE Version

• Command-Line Options

• Environment Variables

• Fatal Error Log

• Core and Crash Dump

• Logs and Traces

Detailed Description of the Problem

When creating a problem description, try to include as much relevant information as possible.

Describe the application, the environment, and the most important events leading up to the time when the problem happened.

Report all troubleshooting steps and results that have already occurred.

Sometimes, the problem can be reproduced only in a complex application environment. In this case, the description, coupled with logs, core file, and other relevant information, might be the only way to diagnose the issue. In these situations, the description should indicate if the submitter is willing to run further diagnostics or run test binaries on the system where the issue occurs.

• If the problem is reproducible at will, then list the steps that are required to demonstrate the problem.
• If the problem can be demonstrated with a small test case, then include the test case and the commands to compile and execute the test case.
• If the test case or problem requires third-party code, such as a commercial or open source library or package, then provide then details about where and how to obtain the library.

Hardware Details

The hardware details are stored in the error logs when a fatal error occurs.

Sometimes, a bug happens or can be reproduced only on certain hardware configurations. If a fatal error occurs, then the error log might contain the hardware details. If an error log is not available, then document in the bug report the number and the type of processors in the machine, the clock speed, and, where applicable and if known, some details on the features of that processor. For example, in the case of Intel processors, it might be relevant that hyper-threading is available.

Operating System Details

Operating systems provide commands that you can use to get the operating system details.

On Linux, it is important to know which distribution and version is used. Sometimes the /etc/*release file indicates the release information, but because components and packages can be upgraded independently, it is not always a reliable indication of the configuration. Therefore, in addition to the information from the *release file, collect the following information:

• The kernel version: This can be obtained using the uname -a command.
• The glibc version: The rpm -q glibc command indicates the patch level of glibc.
• The thread library: There are two thread libraries for Linux, namely LinuxThreads and NPTL. The LinuxThreads library is used on 2.4, and earlier kernels and has fixed stack and floating stack variants. The Native POSIX Thread Library (NPTL) is used on the 2.6 kernel. Some Linux releases (such as RHEL3) include backports of NPTL to the 2.4 kernel. Use the command getconf GNU_LIBPTHREAD_VERSION to determine which thread library is used. If the getconf command returns an error to say that the variable does not exist, then it is likely that you are using an old kernel with the LinuxThreads library.

Java SE Version

Obtain the Java SE version string with the java -version command.

Multiple versions of Java SE may be installed on the same machine. Therefore, ensure that you use the version of the java command used by the failing application. It is very likely to be different from the default java command included in a user's PATH environment variable.

Command-Line Options

If the bug report does not include a fatal error log then, it is important to document the full command line and all its options. This includes any options that specify heap settings, for example, the -Xmx option, or any -XX options that specify HotSpot specific options.

If you can reproduce the issue at will, and you're able to read standard output (stdout) for the JVM, then you can add the -XX:+PrintCommandLineFlags option to obtain the full list of command-line options used by the application. This option will be active the next time the JVM is restarted.

You can also run the jcmd command as follows to obtain the command-line options of a running VM:

jcmd <process ID for the Java process> VM.command_line

In addition, you can change the flags of a running JVM through jcmd. See the VM.set_flag command.

Environment Variables

Sometimes problems arise due to environment variable settings. When creating the bug report, indicate the values of the following Java environment variables (if set).

• JAVA_TOOL_OPTIONS

• _JAVA_OPTIONS

• CLASSPATH

• JAVA_COMPILER

• PATH

• USERNAME

Note:

You should obtain the values of environment variables from the context of the failing application. In addition, one or more configuration files may set the values of these environment variables for that failing application.

In addition, collect the following operating-system-specific environment variables.

• On the Linux operating system, collect the values of the following environment variables:

  • LD_LIBRARY_PATH

  • LD_PRELOAD

• On Windows, collect the values of the following environment variables:

  • OS

  • PROCESSOR_IDENTIFIER

  • _ALT_JAVA_HOME_DIR

Fatal Error Log

When a fatal error occurs, an error log is created. See Fatal Error Log.

The error log contains information obtained at the time of the fatal error, such as version and environment information, details about the threads that provoked the crash, and so forth.

If the fatal error log is generated, then be sure to include it in the bug report or report it during a support call.

Core and Crash Dump

If a core file or crash dump has been created because of the reported issue, include it with the bug, size permitting.

A Linux core file or a Windows crash dump contains the memory state of either an application or the operating system at the time the core or dump was created. Depending on a system's configuration, a core or crash dump may be created automatically when a crash happens. Consult with the system administrator to determine if a core file will be generate automatically and where.

In the case of a hung process, the procedure for generating a dump is described in Collect Core Dumps.

Logs and Traces

Log or trace output can help to quickly determine the cause of a problem.

For example, in the case of a performance issue, the output of the -Xlog:gc JVM command-line option can help in diagnosing the problem. This option enables output from the garbage collector.

In other cases, you can use Java Flight Recorder and JDK Mission Control to capture statistical information over the time period leading up to the problem.

In the case of a deadlock or a hung VM, the thread stacks can help diagnose the problem. Obtain thread stacks by pressing Control+\ on Linux or Control+Break on Windows. Alternatively, use the Thread.dump_to_file option in the jcmd command.

In general, provide all relevant logs, traces, and other output in the bug report or during the support call.

Report a Bug

Once you have concluded that your issue was not already reported and collected data about it, report it at Report a Bug or Request a Feature.

Collect Core Dumps

A core dump or a crash dump is a memory snapshot of a process.

A core dump can be automatically created by the operating system when a fatal or unhandled error occurs. Alternatively, a core dump can be forced by using system-provided command-line utilities. Sometimes, a core dump is useful when diagnosing a process that appears to be hung; the core dump may reveal information about the cause of the hang.

The following sections describe scenarios for collecting core dumps.

• Collect Core Dumps on Linux

• Reasons for Not Getting a Core File

• Collect Crash Dumps on Windows

Collect Core Dumps on Linux

By default, the core dump is created in the current working directory of the process. The name of the core dump file is core.pid, where pid is the process ID of the crashed Java process.

Not all systems are configured to allow the creation of core files. The ulimit utility is used to get or set the limitations on the system resources available to the current shell and its descendants. Use the ulimit -c command to check or set the core file size limit. Ensure that the limit is set to unlimited; otherwise, the core file could be truncated or not produced.

Note:

ulimit is a Bash shell built-in command; on a C shell, use the limit command.

Ensure that any scripts that are used to launch the VM or your application do not disable core dump creation.

You can use the gcore command in the gdb (GNU debugger) interface to get a core image of a running process. This utility accepts the pid of the process for which you want to force the core dump.

To get the list of Java processes running on the machine, you can use any of the following commands:

• jcmd
• ps -ef | grep java
• pgrep java

You can use the ShowMessageBoxOnError option to collect core dumps on Linux. Start a Java process with the -XX:+ShowMessageBoxOnError command-line option. When a fatal error occurs, the process prints a message to standard error and waits for a yes or no response from standard input.

Reasons for Not Getting a Core File

The following is a list of reasons why a core file might not be generated on Linux:

• The application user does not have permission to write in the current working directory of the process.

• The application user has write permission on the current working directory, but there is already a file named core that has read-only permission.

• The current directory does not have enough space.

• The current directory has a subdirectory named core.

• The current working directory is remote. It might be mapped to a Network File System (NFS), and NFS failed at the time the core dump was about to be created.

• The process is running a setuid program, and therefore the operating system will not dump the core unless it is configured explicitly.

• Java specific: If the process received SIGSEGV or SIGILL but did not produce a core file, it is possible that the process handled it. For example, HotSpot VM uses the SIGSEGV signal for legitimate purposes, such as throwing NullPointerException, deoptimization, and so forth. The signal is unhandled by the Java VM only if the current instruction (PC) falls outside the Java VM generated code. These are the only cases in which HotSpot dumps the core.

• Java specific: The JNI Invocation API was used to create the VM. The standard Java launcher was not used. The custom Java launcher program handled the signal by consuming it and produced the log entry silently. This situation has occurred with certain application servers and web servers. These Java VM embedding programs transparently attempt to restart (fail over) the system after an abnormal termination. In this case, the fact that a core dump is not produced is a feature and not a bug.

Collect Crash Dumps on Windows

In the Windows operating system, there are three types of crash dumps: Dr. Watson log file, user minidump, and Dr. Watson full dump.

• Dr. Watson log file, which is a text error log file that includes faulting stack trace and a few other details.

• User minidump, which is considered a partial core dump. It is not a complete core dump, because it does not contain all the useful memory pages of the process.

• Dr. Watson full dump, which is equivalent to a UNIX core dump. This dump contains most memory pages of the process except for code pages.

When an unexpected exception occurs on Windows, the action taken depends on two values in the following registry key:

\\HKEY_LOCAL_MACHINE\Software\Microsoft\Windows NT\CurrentVersion\AeDebug

The two values are named Debugger and Auto. The Auto value indicates if the debugger specified in the value of the Debugger entry starts automatically when an application error occurs.

• A value of 0 for Auto means that the system displays a message box notifying the user when an application error occurs.

• A value of 1 for Auto means that the debugger starts automatically.

The value of Debugger is the debugger command that is to be used to debug program errors.

When a program error occurs, Windows examines the Auto value, and if the value is 0, then it executes the command in the Debugger value. If the value for Debugger is a valid command, then a message box is created with two buttons: OK and Cancel. If the user clicks OK, then the program is terminated. If the user clicks Cancel, then the specified debugger is started. If the value for the Auto entry is set to 1 and the value for the Debugger entry specifies the command for a valid debugger, then the system automatically starts the debugger and does not generate a message box.

The following are two ways to collect crash dump on Windows.

• Configure Dr.Watson:

  The Dr. Watson debugger is used to create crash dump files. By default, the Dr. Watson debugger (drwtsn32.exe) is installed in the Windows system folder (%SystemRoot%\System32).

  To install Dr. Watson as the postmortem debugger, run the following command:

  drwtsn32 -i
  

  To configure the name and location of crash dump files, run drwtsn32 without any options.

  In the Dr. Watson GUI window, ensure that the Create Crash Dump File check box is selected and that the crash dump file path and log file path are configured in their respective text fields.

  Dr. Watson can be configured to create a full dump using the registry. The registry key is shown in the following example.

  System Key: [HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\DrWatson]
  Entry Name: CreateCrashDump
  Value: (0 = disabled, 1 = enabled)
  

  Note:

  If the application handles the exception, then the registry-configured debugger is not invoked. In that case, it might be appropriate to use the -XX:+ShowMessageBoxOnError command-line option to force the process to wait for user intervention on fatal error conditions.
• Force a crash dump:

  The userdump command-line utility can be used to force a Dr. Watson dump of a running process. The userdump utility does not ship with Windows. It is released as a component of the OEM Support Tools package.

  An alternative way to force a crash dump is to use the windbg debugger. The main advantage of using windbg is that it can attach to a process in a non-invasive manner (that is, read-only). Usually, Windows terminates a process after a crash dump is obtained, but with the noninvasive attach, it is possible to obtain a crash dump and let the process continue. To attach the debugger check box requires selecting the Attach to Process option and the Noninvasive check box.

  When the debugger is attached, a crash dump can be obtained using the command shown in the following example.

  .dump /f crash.dmp
  

  The windbg debugger is included in the Debugging Tools for Windows download.

  An additional utility in this download is the dumpchk.exe utility, which can verify that a memory dump file was created correctly.

  Both userdump.exe and windbg require the pid of the process. The userdump -p command lists the process and program for all processes. This is useful if you know that the application is started with the java.exe launcher. However, if a custom launcher is used (embedded VM), then it might be difficult to recognize the process. In that case, you can use the jps command-line utility because it lists the PIDs of the Java processes only.

  You can also use the -XX:+ShowMessageBoxOnError command-line option on Windows. When a fatal error occurs, the process shows a message box and waits for a yes or no response from the user.

  Before clicking Yes or No, you can use the userdump.exe utility to generate the Dr. Watson dump for the Java process. This utility can also be used in cases when the process appears to be hung.