# Debugging transported core dumps

When a core dump is moved to a machine different from the one where it was produced ("transported core dump"), debuggers (dbx, gdb, windbg or SA) do not always successfully open the core dump. This is due to library (shared objects or DLLs) mismatches between the core dump machine and the debugger machine. For this reason you should first consider using one of the following approaches to debugging the core dump rather than transporting it to a different machine:

- Remote login to the machine that the core dump was produced on, and use CLHSDB - SA command line HSDB interface.
- Use SA remote debugging support to remotely debug the core directly on the machine it was produced on. This is done by first running jhsdb debugd on the machine with the core dump, and then attaching to it from another machine by using the jhsdb --connect argument. See the jhsdb man page for details.

  WARNING: jhsdb debugd is deprecated and will be removed in a future release.

With transported core dumps, SA may produce an error message or throw an exception (such as for a missing hotspot symbol) when opening the core dump. Environment variable LIBSAPROC_DEBUG may be set to any value to help debug the root casue of these failures. With LIBSAPROC_DEBUG set, SA prints many messages in standard error which can be useful for further debugging. Note that LIBSAPROC_DEBUG is not supported on Windows.

On most platforms, core dumps do not contain text (code) pages. Their pages are instead read from the executable and shared objects (or DLLs). Therefore it is important to have a matching java executable and shared object files on the debugger machine. The best way to guarantee this match is to match the debugger machine to that of core dump machine. This means having the same OS version and libraries, and also having the same version of the JDK. It also means having the OS libraries and JDK installed in the same locations on both machines. However, often this isn't an option, and instead you need to copy the libraries and java installation from the machine where the core dump was produced to the debugger machine, and you need to tell SA where these are all located. That is done differently for each OS type, and is described in the following sections.

### Using transported core dumps on Linux

On Linux, SA parses core and shared library ELF files. But, you may still face problems with transported core dumps, because matching shared objects may not be in the path(s) specified in core dump file. To workaround this, you can define environment variable SA_ALTROOT to be the directory where shared libraries are kept. In this directory you should copy all the needed JDK libraries, and any other user JNI libraries that were used. You should also copy any referenced linux libraries from the core dump machine, unless they are identical to what are installed on the debugger machine.

You can also use SA_ALTROOT to specify a path mapping. For example, if you set SA_ALTROOT=/altroot, then /altroot will be prepended to any path found in the core file, and also prepended to any subdir with the root part stripped off. For example, when looking up /usr/lib/libfoo.so, SA will try to find /altroot/usr/lib/libfoo.so, /altroot/lib/libfoo.so, and /altroot/libfoo.so.

### Using transported core dumps on Windows

If the debugger machine and core dump machine have identical Windows libraries, then you only need to point SA to the location of the JDK java.exe and libraries. This is done by making sure the bin and bin/server directories are included in the PATH environment variable. Something like the following should work if JAVA_HOME is setup:

`set PATH=%JAVA_HOME%\bin;%JAVA_HOME%\bin\server;%PATH%`

You can also include user JNI libraries in PATH. If the windows libraries are not identical, then they may also need to be copied to the debugger machine and included in PATH.

By default symbols are also located using PATH. However, there are also Java properties that can be used to specify both the location of the binaries, and also separately the location of symbols. Use sun.jvm.hotspot.debugger.windbg.imagePath for the location of binaries, and use sun.jvm.hotspot.debugger.windbg.symbolPath for the location of symbols. imagePath defaults to PATH if not set, and symbolPath defaults to imagePath. The advantage of using these propeties is that you don't need to change your PATH setting, and they allow for binaries to be located separately from symbols.

How you set these properties will depend on the SA tool being used. The following example demonstrates how to set one of the properties when launching the clhsdb tool:

`jhsdb -J-Dsun.jvm.hotspot.debugger.windbg.imagePath="%PATH%;D:\SomePath" clhsdb`

If you are not seeing symbols for Windows libraries, try setting sun.jvm.hotspot.debugger.windbg.symbolPath to include "srv*https://msdl.microsoft.com/download/symbols". Also include PATH so SA will still find your JVM and JNI symbols. For example:

`jhsdb -J-Dsun.jvm.hotspot.debugger.windbg.symbolPath="%PATH%;srv*https://msdl.microsoft.com/download/symbol" clhsdb`

### Using transported core dumps on macOS

SA normally uses the path to the specified java executable to locate the JDK libraries. It will look in the following subdirectories for them (relative to the path to the specified java executable): ../lib, ../lib/server, ../jre/lib, and ../jre/lib/server. If not found in any of those locations, it will look in the same subdirectories relative to the JAVA_HOME environment variable, but using JAVA_HOME normally should not be necessary.

For locating the user JNI libraries, SA uses DYLD_LIBRARY_PATH. It can contain more than one directory separated by a colon. DYLD_LIBRARY_PATH can also be used for locating the JDK libraries, but it needs to specify the full path to the libraries. SA will not automatically search subdirs such as lib/server as it does for JAVA_HOME.

For locating the macOS libraries, SA uses SA_ALTROOT similar to the linux support, except it does not use it to map all the subdirs. It just prepends SA_ALTROOT to the full path of each macOS library. So if you specify SA_ALTROOT=/altroot, SA will prepend /altroot to the full path of each macOS library. Note however, due to JDK-8249779 , SA will not even try to open macOS libraries, so at the moment there is no need to try to match up the macOS libraries by pointing to them with SA_ALTROOT.

Note: Starting with macOS 12, core files are no longer working with macOS on the x64 platform. See JDK-8294316.