install4j Help - Error handling

Debugging on Windows

On Windows, when an installer is executed it always generates a log file in the temp directory that contains information about the JRE search sequence and can be used for debugging purposes. The name of the log file starts with i4j_nlog_. If you have a problem with JRE detection or the installer startup, send this log file along with your support request.

It is also possible to generate this native debug log file for the generated Windows launchers. To switch on logging, define the environment variable

INSTALL4J_LOG=yes

and look for the newest text file whose name starts with i4j_nlog_ in the temp directory. This is done silently, without notifying the user and is also suitable for situations where launchers are called automatically or repeatedly.

An easier way for a user to create a log file is to start the launcher with the argument

/create-i4j-log

The launcher will notify the user where the log is created and will offer to open an explorer window with the log file selected. After the message box is closed, the launcher will continue to start up.

Debugging on macOS

Similar to Windows, macOS launchers also support the INSTALL4J_LOG=yes environment variable definition for debug logging. Rather than writing a log file, they write to the system log. You can display the system log by starting the "Console" application which is located in /Applications/Utilities.

Setting the environment variable can be done by opening a terminal and executing

launchctl setenv INSTALL4J_LOG=yes

Then all newly started applications in the Finder will have this environment variable set. The current terminal will not be affected until you quit the Terminal application and start it again.

Rather than setting the environment variable for all install4j launchers, you can set it for a particular invocation only. To do that, call the Contents/MacOS/JavaApplicationStub inside the application bundle and prefix the call with the definition of the environment variable. For an application bundle "MyApp.app", the call looks like this:

INSTALL4J_LOG=yes MyApp.app/Contents/MacOS/JavaApplicationStub

In this case, the log output will also be written to the terminal. Using /usr/bin/open will not work with this technique, because the latter gets the environment variables from the Finder.

Note that logging only works for GUI launchers and not for command line and service launchers which are implemented as Unix shell scripts. There is no command line argument that activates logging, like on Windows.

Error logs

If an exception is thrown in the installer, it prepares an error log and informs the user about its location

You can force the installer to print exceptions to stderr for debugging purposes with the -Dinstall4j.debug=true command-line option.

Installation log

All installer applications generate an installation log that can be used for debugging purposes. After a successful installation the log file is saved to

<installation dir>/.install4j/installation.log

For an uninstaller or if the installer exited before the "Install files" action was run, you can find it in the temporary directory if you pass -Dinstall4j.keepLog=true to the installer or uninstaller. The file is prefixed i4j_log.

If you would like the installer to log to stderr as well, you can pass -Dinstall4j.logToStderr=true to the installer. Both arguments can also be useful for debug installers and uninstallers, where they have to be passed as VM parameters.

Error handling of Actions

You can define the error handling for every installation or uninstallation action separately. Mor information is available in the DMG options and files on screens and actions.

Return values