G Troubleshooting ADF Faces

This appendix describes common problems that you might encounter when designing the application user interface with the ADF Faces framework and ADF Faces components and explains how to solve them.

This appendix includes the following sections:

In addition to this chapter, review Error Messages for information about the error messages you may encounter.

G.1 About Troubleshooting ADF Faces

While designing the ADF application user interface, you might face problems. Certain guidelines and processes should be followed to identify, diagnose and resolve problems proactively.

This section provides guidelines and a process for using the information in this appendix. Using the following guidelines and process will focus and minimize the time you spend resolving problems.


When using the information in this chapter, please keep the following best practices in mind:

  • After performing any of the solution procedures in this chapter, immediately retry the failed task that led you to this troubleshooting information. If the task still fails when you retry it, perform a different solution procedure in this chapter and then try the failed task again. Repeat this process until you resolve the problem.

  • Make notes about the solution procedures you perform, symptoms you see, and data you collect while troubleshooting. If you cannot resolve the problem using the information in this chapter and you must log a service request, the notes you take will expedite the process of solving the problem.


Follow the process outlined in Table G-1 when using the information in this chapter. If the information in a particular section does not resolve your problem, proceed to the next step in this process.

Table G-1 Process for Using the Information in this Chapter

Step Section to Use Purpose


Getting Started with Troubleshooting the View Layer of an ADF Application

Get started troubleshooting the view layer of an ADF application. The procedures in this section quickly address a wide variety of problems.


Resolving Common Problems

Perform problem-specific troubleshooting procedures for the view layer of an ADF application. This section describes:

  • Possible causes of the problems

  • Solution procedures corresponding to each of the possible causes


Using My Oracle Support for Additional Troubleshooting Information

Use My Oracle Support to get additional troubleshooting information. The My Oracle Support web site provides access to several useful troubleshooting resources, including links to Knowledge Base articles, Community Forums, and Discussion pages.


Using My Oracle Support for Additional Troubleshooting Information

Log a service request if the information in this chapter and My Oracle Support does not resolve your problem. You can log a service request using My Oracle Support at https://support.oracle.com.

G.2 Getting Started with Troubleshooting the View Layer of an ADF Application

Builtin error messages in Oracle ADF alerts users of a problem and also identifies the layer of the application that is causing the problem. To optimizing ADF Faces troubleshooting, certain configuration options should be set.

Oracle ADF has builtin error messages that enable you to determine which layer of your application may be causing a problem. Error messages are the starting point for troubleshooting. You can look up error messages in Error Messages, and you may research a particular error message on the web. Error messages that originate from your ADF Business Components model layer will have a JBO prefix, whereas all other ADF layer components, including the ADF Face view layer, will appear as a Java error message with an Oracle package.

Once you are able to identify the layer, you may run diagnostic tools. You may also view log files for recorded errors. You can search the technical forums on Oracle Technology Network for discussions related to an error message. Each of the component layers for Oracle ADF has its own dedicated forum. You can access the forum home page for JDeveloper and Oracle ADF under the Development Tools list on Oracle Technology Network at https://forums.oracle.com/forums/main.jspa?categoryID=84.

Before you begin troubleshooting, you should configure the ADF application to make finding and detecting errors easier. Table G-2 summarizes the settings that you can follow to configure the view layer of an ADF application for troubleshooting.

Table G-2 Configuration Options for Optimizing ADF Faces Troubleshooting

Configuration Recommendation Description

Enable debug output.

To enable debug output, set the following in the trinidad-config.xml file:

<adf-faces-config xmlns=

Improves the readability of HTML markup in the web browser:

  • Line wraps and indents the output.

  • Detects and highlights unbalanced elements and other common HTML errors, such as unbalanced elements.

  • Adds comments that help you to identify which ADF Faces component generated each block of HTML in the browser page.

Disable content compression.

To disable content compression, set the following in the web.xml file:


Improves readability by forcing the use of original uncompressed styles.

Unless content compression is disabled, CSS style names and styles will appear compressed and may be more difficult to read. For more information about how disabling content compression affects readability, see the "Applying the Finished ADF Skin to Your Web Application" in Developing ADF Skins.

Disable JavaScript compression.

To disable JavaScript compression, set the following in the web.xml file:


Allows normally obfuscated JavaScript to appear uncompressed as the source.

Enable client side asserts.

To enable client side asserts, set the following in the web.xml file:


Allows warnings of unexpected conditions to be output to the browser console.

Enable client side logging.

To enable client side logging, set the following in the web.xml file:


Allows log messages to be output to the browser console.

Unless client side logging is enabled, log messages will not be reported in the client.

Enable more detailed server side logging.

To enable more detailed server side logging, shut down the application server and then enter the following setting in the logging.xml file, and restart the server:

<logger name="oracle.adf.faces" level="CONFIG"/>


Use the WLST command:

setLogLevel(logger="oracle.adf" level="CONFIG", addLogger=1)


In Oracle Enterprise Manager Fusion Middleware Control, use the Configuration page to set oracle.adf, oracle.adfinternal, and oracle.jbo to level CONFIG.

Allows more detailed log messages to be output to the browser console.

Unless server side logging is configured with a log level of CONFIG or higher, useful diagnostic messages may go unreported.

Allowed log level settings are: SEVERE, WARNING, INFO, CONFIG, FINE, FINER, FINEST, ALL. Oracle recommends CONFIG level or higher; the default is SEVERE.

Disable HTTP cache headers.

To disable HTTP cache headers, set the following in the web.xml file:


Forces reloading of patched resources.

Unless HTTP cache headers are disabled, the browser will cache resources to ensure fast access to resources.

After changing the setting, clear the browser cache to force it to reload resources.

G.3 Using Test Automation for ADF Faces

It is important to test that the user interface of your ADF application performs as expected. There are tools that can help you achieve such automation of your UI testing to increase the effectiveness, efficiency and coverage of your UI testing.

This section describes best practices for using the ADF Faces test automation framework.

G.3.1 Enabling Test Automation for ADF Faces

You can enable test automation by setting the oracle.adf.view.rich.automation.ENABLED parameter in the application’s web.xml file. This parameter notifies ADF Faces that test automation is being used and turns on external component id attributes. Note that this parameter only enables the infrastructure for test automation; it does not initiate testing itself, which requires a tool such as the open source Selenium IDE.

Tests that you write that rely on the internal component id are always guaranteed to have a value. The disadvantage is that the internal component id values may change between ADF Faces releases to support framework enhancements. Therefore, the tests that you write must not rely on the component id. To build more robust automated tests, rely on absolute locator id attributes and check that these attributes have a value.

The oracle.adf.view.rich.automation.ENABLEDparameter accepts the following values:

  • OFF: Indicates the test automation is disabled. This is the appropriate setting for a production environment.

  • FULL: Notifies ADF Faces that test automation is being used and turns on external component id attributes. Use this setting with caution, and only in a protected testing environment.


    When the test automation context parameter is set to FULL, the oracle.adf.view.rich.security.FRAME_BUSTING context parameter behaves as though it were set to never. The security consequence of disabling framebusting is that pages of your application will become vulnerable to clickjacking from malicious websites. For this reason, restrict the use of the test automation to development or staging environments and never enable test automation in a production environment. For more information, see Framebusting.

  • SAFE: Notifies ADF Faces that test automation is being used and turns on external component id attributes. This setting is the same as FULL, with the following differences in how it treats secure information.

    • It does not disable framebusting. That is, the oracle.adf.view.rich.security.FRAME_BUSTING context parameter does not behave as though it were set to never.

    • JSESSIONID will be encrypted.

    • Version number information, described in Version Number Information will not be shown.

    • Logging to the server is disabled.

Performance Tip

When you enable test automation, a client component is created for every component on the page. Therefore, set this parameter to OFF in a production environment.

The oracle.adf.view.rich.automation.ENABLED context parameter that you define in the application’s web.xml file is EL bindable. For example, you might want the application to programmatically set test automation mode for a single test user, for all users of the application, or for a particular user group. The following example shows how to use an EL expression to set test automation mode for a test user.

   #{securityContext.userName == 'testuser' ? 'SAFE' : 'OFF'}

If you enable automation and set oracle.adf.view.rich.automation.ENABLED to SAFE or FULL, a response cookie is enabled automatically. This response cookie indicates that the request is coming from an automation run that allows the server to limit the incoming automation traffic.

Enabling test automation also enables assertions in the running application. If your application exhibits unexpected component behavior and you begin to see new assertion failed errors, you will need to examine the implementation details of your application components. For example, it is not uncommon to discover issues related to popup dialogs, such as user actions that are no longer responded to.

Here are known coding errors that will produce assertion failed errors only after test automation is enabled:

  • Your component references an ADF iterator binding that no longer exists in the page definition file. When assertions are not enabled, this error is silent and the component referencing the missing iterator simply does not render.

  • Your component is a partial trigger component that is defined not to render (has the attribute setting rendered="false"). For example, this use of the rendered attribute causes an assertion failed error:

    <af:button  id="hiddenBtn" rendered="false" text="Test"/>
    <af:table var="row" id="t1"  partialTriggers="::hiddenBtn">

    The workaround for this error is to use the attribute setting visible="false" and not rendered="false".

  • Your components were formed with a nesting hierarchy that prevents events from reaching the proper component handlers. For example, this nesting is incorrect:


    and should be rewritten as:



System administrators can enable test automation at the level of standalone Oracle WebLogic Server by starting the server with the command line flag -Doracle.adf.view.rich.automation.ENABLED= automation-mode. Running your application in an application server instance with test automation enabled overrides the web.xml file context parameter setting of the deployed application.

G.3.2 Simulating Mouse Events in ADF Faces Test Automation

During test automation, you can simulate mouse events that you can use to test mouse events. To simulate mouse events, you need to first add a test harness that you can use to set up the environment for a test simulation mouse click before the test-engine mouse-click simulation occurs. The test harness calls the following function.

AdfPage.prototype.simulateMouse = function(locator, mouseEvent)

Before you call the function, you need to update your test engine to call the API.

The sample API is given below:

  * Simulate mouse type event using locator.
  * @param {String} locator locator string in the format <scopedId>#<subid>
  * @param {Object} javascript object containing a sparse set of mouse event name value pairs that will
  *                 be used to create a mouse event. Defaults will be used for any missing fields.
  *                 The defaults are as follows:
  *                     type: “click”
  *                     canBubble: true
  *                           cancelable:true
  *                     view: the current window
  *                     detail: 1
  *                     screenX: 0
  *                     screenY: 0
  *                     clientX: the client location of the X coordinate of the center of the DOM
  *                              element returned by the locator
  *                     clientY: the client location of the Y coordinate of the center of the DOM
  *                              element returned by the locator
  *                     ctrlKey: false
  *                     altKey: false
  *                     shiftKey: false
  *                     metaKey: false
  *                     button: 0
  *                     relatedTarget: null
  *                 If no mouseEvent is provided, a mouseEvent with all of the defaults will be used.
  * @abstract

After you prepare the environment for the mouse event, this method defers to a test engine class instance that you will define. By doing so, you are pointing the test engine class instance back to your normal test engine to test the mouse event. That class continues to do the normal test procedure for a mouse event that you did before the start up of the mouse event.

Now create a test engine class to be an instance of the new abstract API class. Your test engine implementation needs to override this method:

AdfDhtmlTestEngine.prototype.simulateDomMouse = function(domElement, mouseEvent)

Following is an example of an instance of AdfDhtmlTestEngine, where you need to add the call to the test framework mouse event code that you just created.

  * Used for testing a custom implementation of AdfDhtmlTestEngine.
function CustomTestEngine()

// make CustomTestEngine a subclass of AdfDhtmlTestEngine
AdfObject.createSubclass(CustomTestEngine, AdfDhtmlTestEngine);

  * Simulate mouse event on a dom element.
  * @param {String} domElement the domElement receiving the mouse event 
  * @param {Object} javascript object containing a sparse set of mouse event name value pairs.  
  * @Override  
CustomTestEngine.prototype.simulateDomMouse = function(domElement, mouseEvent)
// Here, call your custom test framework to actually do the mouse event, now that the environment is all ready for this event. 

Finally, ADF should be aware of the new test engine class. You can specify this using the web.xml parameter. This is important for the functioning of test setup code, like AdfPage.PAGE.simulateMouse(), that needs to invoke the testing framework function after doing any necessary setup work.

This parameter specifies the automation test engine that is being used.

G.4 Resolving Common Problems

There are some common problems that may arise while developing your ADF application user interface. The list of problems with their causes and possible fixes will help you to resolve issues.

This section describes common problems and solutions.

G.4.1 Application Displays an Unexpected White Background

The ADF application has a default skin that displays a simple or minimal look and feel. The background of the default skin will appear white.


The skin JAR files did not get deployed correctly to all applications.


To resolve this problem:

  1. Check that the skin JAR files have been deployed to all applications.
  2. Check that the skin name is not misspelled in the profile options, as described in the "Applying the Finished ADF Skin to Your Web Application" chapter in Developing ADF Skins.

G.4.2 Application is Missing Expected Images

The skin application must be packaged as an ADF Library JAR file that includes the image files.


The skin JAR files were not packaged correctly.


To resolve this problem:

  1. Check that the correct target application version was specified when creating the skin application.
  2. Repackage the skin application and create a new ADF Library JAR file, as described in the "Packaging an ADF Skin into an ADF Library JAR" section in Developing ADF Skins.

G.4.3 ADF Skin Does Not Render Properly

The ADF skin that you created defines style properties that do not render in the browser as expected.


Not all ADF skin selectors may be customized and customizing non-valid selectors may result in unexpected or inconsistent behavior for your application.


To resolve this problem:

  1. Check the setting of the context initialization parameter in the web.xml file. Not all changes that you make to an ADF skin appear immediately if you set the CHECK_FILE_MODIFICATION parameter to true. You must restart the web application to view changes that you make to icon and ADF skin properties.
  2. Check that you customized only valid ADF skin selectors, pseudo-elements, and pseudo-classes, as described in the skinning sections of the ADF Faces component and ADF Data Visualization (DVT) component chapters of this guide.

G.4.4 ADF Data Visualization Components Fail to Display as Expected

Various ADF Data Visualization (DVT) components rely on Flash to display correctly and unless Flash is supported by the platform and browser, your application may not display visual aspects of the DVT components.


Not all platforms and browsers support Flash. This will force the application to downgrade to the best available fallback. If the platform is not supported, the application displays according to the flash-player-usage setting in the adf-config.xml file.


To resolve this problem, reinstall the latest Flash version available for your browser.

G.4.5 High Availability Application Displays a NotSerializableException

When you design an application to run in a clustered environment, you must ensure that all managed beans with a life span longer than one request are serializable.


When the Fusion web application runs in a clustered environment, a portion of the application's state is serialized and copied to another server or a data store at the end of each request so that the state is available to other servers in the cluster. Specifically, beans stored in session scope, page flow scope, and view scope must be serializable (that is, they implement the java.io.Serializable interface).


To resolve this problem:

  1. Enable server checking to ensure no unserializable state content on session attributes is detected. This check is disabled by default to reduce runtime overhead. Serialization checking is supported by the system property org.apache.myfaces.trinidad.CHECK_STATE_SERIALIZATION. The following are system properties and you must specify them when you start the application server.
  2. For high availability testing, start off by validating that the Session and JSF state is serializable by launching the application server with the system property:


  3. Add the beans option to check that any serializable object in the appropriate map has been marked as dirty if the serialized content of the object has changed during the request:


  4. If a JSF state serialization failure is detected, relaunch the application server with the system property to enable component and property flags and rerun the test:


G.4.6 Unable to Reproduce Problem in All Web Browsers

You run the application in Microsoft Windows Internet Explorer and verify a problem but when you run the application in Mozilla Firefox, the problem does not reproduce. These problems are often visual in nature, such as unintended extra space separating areas within a web page.


Settings between browsers vary and can lead to differences in the visual appearance of your application.


To resolve this problem:

  1. Check browser security settings to ensure they are not misconfigured. For example, confirm that you have not disabled JavaScript, XML HTTP, or popups.
  2. Confirm that Internet Explorer is not being run in compatibility mode. If you see a dialog that states "the current compatibility setting is not supported," disable compatibility mode in the browser’s Tools menu.
  3. If you observe a JavaScript error, then it is most likely a bug in the browser. However, it could be an ADF Faces-specific JavaScript error.
  4. Optionally, configure an @agent at-rule in the ADF skin file of the application to define an appearance specific to the desired browser. For more information, see the "Working with At-Rules" chapter of Developing ADF Skins.

G.4.7 Application is Missing Content

The application pages may display areas that appear empty where content is expected.


The cause depends on the application design. For example, authorization that you enforce in the application may be unintentionally preventing the application from displaying content. Or, when portlets are used, the portlet server may be down.


To resolve this problem:

  1. Check the log file for exceptions. Oracle recommends changing the log level to a lower level than SEVERE. For information about Oracle Fusion Middleware logging functionality, see the "Managing Log Files and Diagnostic Data" chapter of Administering Oracle Fusion Middleware.
  2. Look for struck threads, as described in the "Monitor server performance" topic in the Oracle WebLogic Server Administration Console Online Help. If you find a stuck thread, examine the thread stack dump.
  3. If you observe an HTTP 403 or 404 error on partial page rendering (PPR), then it is most like a bug.

G.4.8 Browser Displays an ADF_Faces-60098 Error

The application returns a runtime exception in a place that was not expected and is not handled.


ADF Faces has received an unhandled exception in some phase of the lifecycle and will abort the request handling.


To resolve this problem:

  1. This is most likely a logic error in the application.
  2. Verify that the server load or the application is not in distress.

G.4.9 Browser Displays an HTTP 404 or 500 Error

The application does not navigate to the expected page and displays an HTTP 404 file not found error or an HTTP 500 internal server error.


The cause may be traced to the application server.


To resolve this problem:

  1. Verify that the application server is running and that the application is not in distress, as described in the "Monitor server performance" and "Servers: Configuration: Overload" topics in the Oracle WebLogic Server Administration Console Online Help.
  2. Check for hung threads.

G.4.10 Browser Fails to Navigate Between Pages

The application fails to navigate to and open an expected target web page.


The cause may depend on the application design or the cause may be traced to the application server.


To resolve this problem:

  1. Check for unhandled exceptions specific to an ADF Faces lifecycle thread, as described in Browser Displays an ADF_Faces-60098 Error.
  2. Look for HTTP 404 or 505 errors, as described in Browser Displays an HTTP 404 or 500 Error.

G.5 Using My Oracle Support for Additional Troubleshooting Information

My Oracle Support is Oracle's official electronic on-line support service. You can log a Service Request to receive personalized, proactive, and collaborative support to resolve issues specific to Oracle ADF.

You can use My Oracle Support (formerly MetaLink) to help resolve Oracle Fusion Middleware problems. My Oracle Support contains several useful troubleshooting resources, such as:

  • Knowledge base articles

  • Community forums and discussions

  • Patches and upgrades

  • Certification information


You can also use My Oracle Support to log a service request.

You can access My Oracle Support at https://support.oracle.com.