Deploying JavaFX Applications


13 Troubleshooting

This page contains some troubleshooting practices to follow if you encounter any problems deploying your JavaFX applications. It contains the following sections.

13.1 Running Applications

Use the following checklist if you have trouble running applications after you package them.

If the tips below do not help to resolve the issue, then:

  • Ask experts in the JavaFX Forum.

  • File a bug to JIRA.

    Describe in detail what you are trying to do, and what exactly does not work as expected. If possible, share a test case to reproduce the problem. Be sure to include information about your environment and your Java and JavaFX versions.

13.2 Development Process Issues

  • Verify that you use the latest version of JavaFX tools.

  • javafxpackager command fails:

    • Ensure that the JDK bin folder, where javafxpackager utility resides, is on the PATH.

    • Ensure JAVA_HOME is set.

    • On Mac, the problem could be due to simultaneous use of Apple's JDK 6 and Oracle's JDK 7. To work around them, set JAVA_HOME and add it to the path.

      • export JAVA_HOME=/Library/Java/JavaVirtualMachines/jdk1.7.0_06.jdk/Contents/Home

      • export PATH=$JAVA_HOME/bin:$PATH

  • Packaging self-contained applications:

    • If the package format you are trying to build depends on third-party tools, then make sure they are available on the PATH.

    • Set verbose="true" in the <fx:deploy> task or pass "-v" to javafxpackager to get verbose build output.

    • Set the environment variable JAVAFX_ANT_DEBUG to true to get additional details and keep intermediate build artifacts.

    • If drop-in custom resources are not used, then verify that the JavaFX Ant task definitions are loaded with the correct classpath, typically with "." at the beginning. See Using JavaFX Ant Tasks

  • Packaging self-contained applications on remote systems:

    • If packaging tools are executed on remote system (e.g. Jenkins, Hudson, and other build systems) to produce the artifact, then it is important to have same user logged on a desktop system. If using the same user login is not possible, you can create a custom .dmg bundle as follows:

    1. Create a .dmg image from manual build

    2. Convert the .dmg file to a read-write form

    3. Remove the content of you application folder, but keep the top level app directory

    4. Add the dmg to the build

    5. At the build time, mount it, copy .app contents to the image, then convert .dmg to a compressed read only form

  • NetBeans issues:

    • Ensure you are using NetBeans 7.2 or later

    • If a Clean and Build fails to build sample application or double-clicking some or all of the files results in an error, check that the JavaFX platform is enabled properly in NetBeans. See "Setting Up NetBeans IDE With JavaFX".

    • To get more insight into the build process, enable verbose output by clicking the Tools icon in the build output window.

    • To build self-contained applications, ensure that the required third-party tools are added to the PATH before you start NetBeans. See Section 6.4, "Installable Packages."

13.3 Runtime Issues

Basic checklist:

  • Verify that you have the latest version Java installed (Java 7 update 6 or later).

  • Before trying to troubleshoot your application, ensure the JavaFX samples run properly.

    1. Download the JavaFX samples zip file.

    2. Double-click the JAR file, the JNLP file, and the HTML file for at least one sample to ensure it runs correctly.

  • Validate that the java process is using your Java Runtime installed location.

  • If you have a 64-bit system, you may be using either a 32 -or 64-bit version of Java. The best way to avoid problems caused by unexpected use of an older version of Java Runtime is to keep both 32- and 64-bit versions of Java up to date.

13.3.1 Standalone Execution

  • Run the same application from the command line as
    java -jar MyApp.jar

    This way you can see actual exceptions and trace messages (if any).

  • Pass "-Djavafx.verbose=true" to enable verbose output from the embedded launcher.

  • If your application starts slow, then it could be due to network configuration. Try disabling the autoproxy configuration by passing "-Djavafx.autoproxy.disable=true" to see if it helps.

  • Do not forget that it is just a Java application, and you can use your favorite techniques to troubleshoot it.

13.3.2 Self-Contained Applications

  • Run the native launcher from the console window to see trace messages and so on.

    • On Mac, the launcher is

    • On Windows, you must pass the "/Debug" option to the launcher to open a window to see the trace messages.

  • You can pass debug options to your application with <fx:jvmarg> or <fx:property> at package time. Examples:

    • To list all classes loaded, add the following to your <fx:deploy> task:

      <fx:jvmarg value="-verbose:class"/>
    • To debug:

      <fx:jvmarg value="-agentlib:jdwp=transport=

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

    • To profile in Netbeans 7.2 on Mac OS X:

      <fx:jvmarg value="-agentpath:/Applications/NetBeans/NetBeans


      This will stop the application after it is loaded until the profiler is attached. Consult the documentation on your profiler for exact values to pass.

  • Review the tips for troubleshooting standalone applications.

  • Mac OS X: if other users cannot run your application, then ensure it is signed See Section, "Mac OS X.")

    • To validate signing, use

      codesign -v -d --verbose=4

13.3.3 Web Start

  • If you rebuilt the application but do not see changes in the runtime, exit the application and clear the Java cache, as follows:

    1. Run javaws -viewer from the command line, or open Java Control Panel manually (for example, by choosing Java in Windows Control Panel).

    2. In Java Control Panel, in the Temporary Internet Files section, click Settings, then click Delete Files.

    3. Select Cached Applications and Applets and click OK.

  • If the application fails with an error, then check the process list to see what java process is actually used to run it. Ensure it comes from correct place.

  • Consult the Java SE 7 Desktop Troubleshooting Guide for tips on how to troubleshoot generic Java Web Start problems.

13.3.4 Applications Embedded in the Browser

  • Validate your version of Java at

  • Check the JavaScript error console for errors.

  • Try a different browser. See if the problem is common to the system or is browser-specific.

    Remember that not all browsers are supported. For example, Chrome on Mac OS X is not supported.

  • Find out the architecture of the browser you are using. Most of the browsers are 32-bit even if you are using a 64-bit platform.

    Install/upgrade 32-bit Java and JavaFX runtimes to resolve the problem.

  • Review the browser's list of installed plugins.

    • There should be one and only Java Plugin on the list. For JavaFX 2.2 and Java 7 update 6 the correct plugin is version 10.6.*.

    • On Windows, there should be one and only one Deployment Toolkit plugin, and it should be the same or a higher version than that of the Java Plugin.

  • Safari 6 on Mac if the file:// protocol is used:

    • According to default Safari 6 policy, "no file:// is allowed to open any local resources that might run code". This means that JavaFX applications will not load and appear to get stuck on the spinning wheel.

    • Run a local web server or disable local file restrictions. To do this, enable the Develop menu, then check the Disable Local File Restrictions menu item.

  • See the Java SE 7 Desktop Troubleshooting Guide for tips on how to troubleshoot generic Java plug-in problems.

13.3.5 Disabling the Autoproxy Configuration in the Code

By default, JavaFX application proxy settings are taken from the current browser if the application is embedded into a web page, or system proxy settings are used. Sometimes SOCKS proxy settings, specified in the System.setProxy are ignored.

If you need to disable the automatic proxy configuration in the application, specify a JavaFX-Feature-Proxy manifest entry in the fx:jar with the None as a value as in the following example.

    <attribute name="JavaFX-Feature-Proxy" value="None"/>

Once you enter the JavaFX-Feature-Proxy manifest, the network stack will not be initialized prior to application code gets executed and you can set socks properties in the code.