Exit Print View

Troubleshooting Guide for Java SE 7 Desktop Technologies

Print View

Document Information


1.  Introduction

2.  AWT

3.  Java 2D

4.  Swing

5.  Internationalization

6.  Java Sound

7.  Applets and Java Web Start Applications

7.1 Configuration Problems

7.1.1 Validation

7.1.2 Common Configuration Problems

7.1.3 Managing Java Runtimes

7.1.4 Passing parameters to the JRE

7.1.5 Java Deployment Home

7.1.6 Deployment Tracing Information

7.1.7 Deployment Cache

7.1.8 Network Configuration

7.2 Applet Troubleshooting

7.2.1 Applet Does Not Start - Plugin Cheat Sheet

7.2.2 Unresponsive Web Page

7.3 Avoiding Security Dialogs

7.3.1 Signed Applications

7.3.2 Mixed Code Issues

7.4 Development Tips

7.4.1 Debugging Applets and Web Start Applications

7.4.2 Profiling Applets and Java Web Start Applications

7.4.3 Debugging Memory Leaks

8.  Submitting Bug Reports

A.  Java 2D Properties

B.  Fatal Error Log

Chapter 7

Applets and Java Web Start Applications

This chapter describes some problems and solutions related to deploying Java applications.

7.1 Configuration Problems

7.1.1 Validation

If your application will not run, perform the following checks:

Verify that the Java Plugin is working.

  1. Go to the http://java.com/en/download/installed.jsp.
  2. Click on the Verify Java version button.
  3. If you see that the expected Java technology version is reported, then the plugin is enabled and found.

Check that your browser knows about the Java plugin.

Make sure the Java Runtime Environment is installed.

7.1.2 Common Configuration Problems

There is no Java Runtime installed.
It is not sufficient to install the Java Developer Kit. A JRE is required to be able to run an applet or webstart. Note that if you use a 64-bit browser, then the 64-bit version of the JRE is required. Likewise, the 32-bit JRE is necessary for 32-bit browsers.
Latest matching plugin/webstart is always used.
There could be just one plugin registered in the browser and the JRE will always register plugin from latest JRE on the system as active. The only way to ensure use of an older plugin is used is to uninstall newer JREs.
Any change in the Java Runtime configuration requires the browser to be restarted
Java is not enabled.
There are multiple places where Java could be disabled. Check the Java Control Panel and your browser plugins/addons list.
Make sure new generation plugin is enabled.
Unless you need to run in the legacy mode, make sure "New generation plugin" is enabled in the Java Control Panel.
Java Control Panel fails to make changes in the Java config.
On Windows 7 or Windows Vista systems with UAC on, the Java Control Panel may fail to update global registry settings. To work around this, make sure you launch Java Control Panel as Administrator if you need to alter these settings.
Javascript needs to be enabled.
If javascript is disabled, then an attempt to launch a Java applet may fail at very early stage.

7.1.3 Managing Java Runtimes

You can use the Java Control Panel tool to manage the list of installed Java Runtime Environments and their behavior. The Java Control Panel can be launched from the bin directory of the JRE installation folder. On Windows operating systems, you can also access it from Control Panel > Java.

Use Java Control Panel if you need to:

JRE list available from Java Control Panel

7.1.4 Passing parameters to the JRE

Troubleshooting, debugging, profiling and other development activities may require launching JVM with a special set of parameters. One way to accomplish this is to use the Java Control Panel.

Open the Java Control Panel, go to the Java tab, then click on the View button. Select the Runtime Parameters cell for the JRE you wish to change and enter parameters into this cell.

Note that these changes are "global" — any Java Web Start application or applet that will be run using this version of JRE will have these parameters set (in addition to what the applet tag or JNLP file may specify).

To pass parameters to a specific JVM used with Java Web Start or an applet, use one of the following techniques:

7.1.5 Java Deployment Home

This is the place where main configuration files are kept. The location is specific to your operating system:

7.1.6 Deployment Tracing Information

Both Java Plug-in and Java Web Start can print trace information into trace files. This includes log information from the JRE itself as well as everything your application may be printing to System.out or System.err.

To get access to trace information, follow these steps:

  1. Open the Java Control Panel (<JRE directory>/bin/ControlPanel).
  2. Select the Advanced tab.
  3. In the Debugging category, check the Enable tracing check box.
  4. Optionally, in the Java console category, select the Show console radio button to see trace information in the console window. The full trace still will be saved to a file.

The trace file is saved into the log directory in the Java deployment home directory (see the previous section). The file name has the prefix javaws or plugin, depending on what you are running. One trace file is produced per process, but one application can be launched using several processes.

To get the maximum level of detail in the trace file, edit the deployment.properties file (which is located in the Java deployment home directory) and add the following line:


By default, a maximum of five trace files are created. The oldest trace files are automatically deleted. To change this limit of maximum number of trace files, add the following line to the deployment.properties file:

deployment.max.output.files=<maximum number of trace files>

You can use the Java Console to view the trace log at runtime. By default, the Java console is hidden. Enable it in the Java Control Panel.

7.1.7 Deployment Cache

Application jars and resources are cached on the disk to avoid loading them the next time they are needed.

The default location of the cache depends on the operating system and can be overidden in the Java Control Panel.

Settings and controls for the cache are available in the General tab of the Java Control Panel, in the Temporary Internet Files section. Click Settings... to change the location and size of the cache. Click View... to see what files are in the cache.

You can clean the cache by running javaws -uninstall, or go to the Java Control Panel's General tab, click View..., and delete files manually. You can also use the Java Control Panel to uninstall individual applications and extensions.

7.1.8 Network Configuration

In general, Java Web Start applications use the system network configuration by default, and applets use the browser network settings. You can set network proxies explicitly using Java Control Panel.

In particular, the Java technology networking layer automatically detects what networking stack to use. However, sometimes autodetection does not work and you may observe "Permission Denied" exceptions trying to open a socket to download your application or applet, even while the same URL is accessible using the same proxy settings with other tools. This problem was observed on some Windows 7 systems when VPN software is used. This can be resolved by explicitly passing a parameter to the JVM:


See the section on how to pass parameters to JVM for details.

7.2 Applet Troubleshooting

For modern browsers which support tabs, each tab might be a separate browser process. If a Java applet is embedded in a browser page and the next generation plugin is being used, usually the process associated with the browser tab creates a JVM within the process (browser VM). The browser VM will create another JVM process (client VM) which will run the applet and manage the applet's lifecycle. The client VM is a Java process (java.exe on Windows and java on Linux/Solaris platforms).

7.2.1 Applet Does Not Start - Plugin Cheat Sheet

If your applet does not start, make sure to enable tracing and the Java console as explained previously. Then use hits below to find reason why applet does not work:

Consult the sections below for further advice.

Browser or Java Process Crash

A crash could be caused by a platform or application issue.

Typically, if a crash happens in the JVM then there should be hs_err_*log file created in the current working directory (on Windows it is often placed on desktop). It is the same crash report file as for standalone applications. Use Appendix B to read it.

Note that if you can spot native libraries loaded from the deployment cache directory, especially if you see code from these libraries in the crash stack, it is very likely to be bug in the application.

Otherwise it is a JRE bug and needs to be reported to bugs.sun.com.

Browser JVM Troubleshooting

To get more details about a JVM running in the browser process, set the following two environment variables before starting the browser:


On Windows, there should be a command window associated with the browser process. All browser VM debug output goes into the command window. Check to see if any exceptions are visible there. A Java thread dump can be obtained by using the "Ctrl-Break" key sequence on the command window.

On Linux and Solaris platforms, after setting the above variables, start the browser from the same session. All browser VM debug output goes into the terminal window. To get a Java thread dump, on a separate terminal, use kill -3 pid or kill -SIGQUIT pid, where pid is the process id of the browser process.

There are "heartbeat" messages sent between the client VM and browser VM. The "heartbeat" messages can be turned off by setting the JPI_PLUGIN2_NO_HEARTBEAT environment variable to 1. This will help isolate whether the problem is "heartbeat" related.

If the log is not opening and environment variables are set in the browser process, then it is likely that the JRE is not installed correctly or Java is disabled. Check for configuration errors and try to reinstall the JRE if nothing else helps.

Client JVM troubleshooting

Check the latest trace file for ideas.

Note that the same client JVM may be shared between multiple applets. Sometimes intermittent failures happen because the shared JVM does not have enough resources available (for example, heap size). In that case, a page reload often helps to resolve the problem.

If application fails with an out of memory error, the heap size needs to be increased. This can be done in the application deployment descriptor (JNLP file) or in the Java Control Panel using Runtime Parameters for JRE in use.

If an application is signed and the user declined a security dialog, this may cause application failure. The decision made by the user is remembered until the JVM is restarted. To see the security dialog again, the user may need to restart the browser.

Note that applet can be deployed to reduce the risk of being affected by other applets and tailor execution environment for the applet's needs. See Applet Deployment in the JDK documentation. In particular, consider using the separate_jvm parameter argument.

7.2.2 Unresponsive Web Page

If page appears to be frozen while an applet starts, or in the runtime, the cause could be Liveconnect calls.

On startup, an attempt to access Java applet from Javascript may block the Javascript engine until applet initialization is complete. It is recommended to postpone Javascript access until the applet is ready and use the enableStatusEvents parameter to unlock non-blocking access to applet status checks. See Applet Status And Event Handlers for details and examples.

To use Liveconnect in runtime, it is recommended to make Javascript calls return quickly to avoid blocking the single-threaded Javascript engine.

Applet or browser hangs

The best source of information in this case is the stack state for both client and browser JVMs.

Use the jstack utility to collect the JVM stack status for the browser JVM (by running jstack browser-pid) and client JVM. Note that jstack may highlight a deadlock if it happens in context of one of these VMs, but it cannot do this if the deadlock involves both processes. In this case, the thread stacks need to be examined manually.

For other approaches, read Troubleshooting Hanging or Looping Processes in the Troubleshooting Guide for Java SE 7 with HotSpot VM.

7.3 Avoiding Security Dialogs

The Java Runtime will automatically warn the user about possible security sensitive issues. If you are confident that applications you use are safe, then it is possible to bypass security dialogs to simplify user experience.

7.3.1 Signed Applications

If a Java applet/webstart application is signed, a certificate security warning dialog box will pop up and the user must click the Run button to give all permissions to the code of application.

To avoid seeing this dialog, you can do one of the following:

  1. User accepts the certificate used to sign the application and selects the check box Always trust content from this publisher. Then next time permissions will be granted to this application automatically (until the certificate expires or is removed from the trusted key store).
  2. The certificate can be manually imported into the JRE trusted certificate store. To import the certificate using the Java Control Panel, choose the Security tab and select Certificates > Trusted Certificates. To import a certificate into the certificate store from the command line, use the keytool utility (in the JRE's bin folder).
  3. Grant AllPermissions in the Java policy file located at ${user.home}/.java.policy, or point to any Java policy file which has AllPermissions in the $(JRE_HOME)/lib/security/java.security file. Permissions can be granted to all applications or restricted to a particular URL. See Default Policy Implementation and Policy File Syntax for more details on .java.policy.

Note: if automatic granting of permissions is not desired, then use the Java Control Panel to remove certificates from trusted certificate keystore. This will result in security dialog box popup again in the future.

7.3.2 Mixed Code Issues

Signed Java Web Start applications and applets that contain signed and unsigned components could potentially be unsafe unless the mixed code was intended by the application vendor. The latest versions of the Java runtime raise a mixed code warning dialog when a program contains both signed and unsigned components and suspicious use is detected.

Bypassing this dialog generally requires making changes to application implementation or repackaging the application. It is also possible to completely disable the software from checking for mixing trusted and untrusted code, but it is not recommended as this allows the user to run potentially unsafe code with no warning and without additional protections. For details on mixed code and ways to bypass this security warning dialog box, please refer to Mixing Signed and Unsigned Code — Ensuring Application and Applet Security.

7.4 Development Tips

For Java Web Start applications and applets, you can use most of techniques available to debug and profile standalone applications, except you will need to use the "attach" mechanism instead of direct launch.

Note that both plugin and Java Web Start will spawn adidtional java or javaw processes that will actually run the JVM executing the application or applet. You need to attach to those processes to be able to collect info about your app. For example, if you want to get a memory dump of your applet, then first you need to figure out the process id for the java process executing the PluginMain class. For example, use the jps utility from the JDK and then use jmap to get a memory dump.

7.4.1 Debugging Applets and Web Start Applications

Just as with standalone Java applications, any JPDA based debugger can be used to debug your applet or Web Start application, for example jdb or the NetBeans debugger.

You will need to enable the JDWP agent for the JVM running your application and specify the port number. Once the JVM is started, you can use your favorite IDE or tools to attach to it.

For details on how to pass arguments to the JVM running applet or Java Web Start application please see section 7.1.4. For example, here is how you can pass details to the Java Web Start application from command line:

bash$ javaws -J-agentlib:jdwp=transport=dt_socket,address=4000,server=y,suspend=y http://acme.com/my/webstart.jnlp

This instructs the agent to suspend after the JVM is initialized and wait for a debugger to connect on port 4000. Please consult this guide for a full description of invocation options.

7.4.2 Profiling Applets and Java Web Start Applications

When you profile a standalone Java application, your favorite IDE is likely be using the JVMTI agent to collect details on program execution. You can do the same for applets and Java Web Start applications but you may need to configure the JVMTI agent explicitly by passing the -agentpath option to JVM. See section 7.1.4 for details on how to pass options to the JVM.

For example,

set _JPI_VM_OPTIONS="-agentpath:C:\Tools\NetBeans\profiler\lib\deployed\jdk16\windows\profilerinterface.dll=C:\Tools\NetBeans\profiler\lib,5140"

Now launch your browser. The NetBeans profile agent is enabled for any applet you will be running in this browser session. You can use NetBeans IDE to attach to the java process. Please consult your profiler documentation for exact details on what agent to use and how to configure it.

7.4.3 Debugging Memory Leaks

Use any techniques available for standalone applications on the process running your applet or application. For example, use jmap to obtain a heap dump, VisualVM or jconsole to observe threads, or pass -XX:+HeapDumpOnOutOfMemoryError to the JVM (see Passing parameters to the JRE) to get a memory dump on error. Use the jps utility to find the process id for the process running your application.