Skip Headers
Oracle® Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework (Oracle Fusion Applications Edition)
11g Release 6 (

Part Number E28163-04
Go to Documentation Home
Go to Book List
Book List
Go to Table of Contents
Go to Feedback page
Contact Us

Go to previous page
PDF · Mobi · ePub

F 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 the Oracle Fusion Middleware Error Messages Reference for information about the error messages you may encounter.

F.1 Introduction to Troubleshooting ADF Faces

This section provides guidelines and a process for using the information in this chapter. 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:


Follow the process outlined in Table F-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 F-1 Process for Using the Information in this Chapter

Step Section to Use Purpose


Section F.2

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


Section F.3

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


Section F.4

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 and Community Forums and Discussion pages.


Section F.4

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

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

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 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, where as 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 look up error messages in the Oracle Fusion Middleware Error Messages Reference. You can also search the technical forums on Oracle Technology Network for discussions related to an error message. Each of the component layers for Oracle ADF has is 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

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

Table F-2 Configuration Options for Optimizing ADF Faces Troubleshooting

Configuration Recommendation Description

Enable debug output.

Enable debug output by setting 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.

Disable content compression by setting 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.

Disable JavaScript compression.

Disable JavaScript compression by setting the following in the web.xml file:


Allows normally obfuscated JavaScript to appear uncompressed as the source.

Enable client side asserts.

Enable client side asserts by setting the following in the web.xml file:


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

Enable clientside logging.

Enable clientside logging by setting 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.

Enable more detailed server side logging shut down the application server, 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.

Disable HTTP cache headers by setting 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.

Optionally, enable performance profiling in the web browser.

Optionally, enable performance profiling in the web browser by setting the following in the web.xml file:


This is normally handled by all recent version browsers.

If needed, Oracle recommends setting the log level to INFO level or higher. Output goes to browser console.

F.3 Resolving Common Problems

This section describes common problems and solutions.

F.3.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 Section 20.2, "Applying Custom Skins to Applications."

F.3.2 Application is Missing Expected Images

The skin application must be packaged as a 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 JAR file, as described in Section 20.7, "Deploying a Custom Skin File in a JAR File."

F.3.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 that 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 Chapter 20, "Customizing the Appearance Using Styles and Skins."

F.3.4 Data Visualization Components Fail to Display as Expected

Various ADF 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.

F.3.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 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 Java server system property org.apache.myfaces.trinidad.CHECK_STATE_SERIALIZATION. The following are Java 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:


F.3.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 the 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 Tool's 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.

F.3.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. Recommend 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 the Oracle Fusion Middleware Administrator's Guide.

  2. Look for struck threads, as described in the "Monitor server performance" topic in Oracle WebLogic Server Administration Console 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.

F.3.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 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.

F.3.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 Oracle WebLogic Server Administration Console Help.

  2. Check for hung threads.

F.3.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 Section F.3.8, "Browser Displays an ADF_Faces-60098 Error."

  2. Look for HTTP 404 or 505 errors, as described in Section F.3.9, "Browser Displays an HTTP 404 or 500 Error."

F.4 Using My Oracle Support for Additional Troubleshooting Information

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:


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

You can access My Oracle Support at