InfoCenter Home >
8: Problem determination

8: Problem determination

Whether you are a beginner or experienced user, the following problem determination section leads you to resources and techniques to help you identify and respond to problems.

Navigate through the problem

Resources for identifying problems

WebSphere Application Server topology



Bookmark the Problem Determination Quick Reference table for a quick reference to the following problem determination information and techniques. The table is a collection of all the resources included in solving your problems.

Navigate through the problem

The following list provides symptoms to identify problems and navigate to recovery. Choose the symptom that best fits your problem - ask yourself What kind of problem is it? and What component is causing the problem?

What kind of problem is it?

Which component is causing the problem?

Choose the product components causing the problem:

Resources for identifying problems

You can perform problem determination at different levels within your system. Several resources are available for identifying problems:

WebSphere Application Server topology

It is important to understand the topology of the system and how your application fits into this topology. The following information explains how the components work together, and disusses the processes necessary for proper function of WebSphere Application Server.

The following is the process and components involved in the WebSphere Application Server "plumbing." Each corresponds to the topology picture below:

  1. The browser sends a URL request to the HTTP server.
  2. The WebSphere Application Server plug-in examines the URL and based on comparisons to the product root/config/plugin-cgf.xml file, dispatches it to the proper servlet (a user-defined servlet or one of the servlets provided).
  3. If the servlet class is not loaded, the dynamic class loader installs the servlet.
  4. Servlet init(), then doGet() or doPost.
  5. Methods are called to do application-specific work.
  6. When enterprise beans are needed, a create is done on a home interface. The home interface is received during initialization from a JNDI lookup.
  7. The Web container instantiated the enterprise bean. If it is an entity bean, then data source and JDBC drivers are used to find out what database URL to use. There is a connection from the connection pool.
  8. Methods are called on the enterprise bean remote interface and executed by the enterprise bean.
  9. SQL is executed. Results are retrieved.
  10. Data beans are created and passed to JSP files.
  11. The JSP file generates the HTML that is sent back through the plug-in to the browser.

For WebSphere Application Server Versions 4.0 and above, use of a Web console is not supported as indicated in the image. You use a Java remote console in Versions 4.0 and above.

See the InfoCenter article 1.3: Prerequisites for information regarding prerequisite information. The administrative database contains configuration information for the administrative server or servers. An application database contains customer application data. database you choose.

During installation, the Web server that will interact with the WebSphere Application Server is identified. Depending on which Web server is identified, a different plug-in code is installed. The plug-in communicates via HTTP to the internal HTTP server, which then routes the requests to the Web container.

The application server also contains two subcomponents, the Web container and EJB container. The Web container interfaces with the plug-in code to service HTTP requests from a Web browser. The EJB container interfaces with the Web container or EJB clients to support access to enterprise beans. Both the Web container or EJB container can access the customer application data.

Protocols

  • RMI/IIOP

    This interface is provided by the CORBA component of the IBM-supplied Java 2 SDK which is installed with WebSphere Application Server. This interface allows an application to transparently access Java objects that are located either locally or remotely. This interface is also used for interactions between the administrative server, the administrative client and the application server.

  • SSL

    SSL encryption is used internally when security is enabled. Web servers can also be configured to use SSL for secure communication with browsers. In addition, SSL can be used for secure communication with browsers like https-type URLs.

  • HTTP

    This interface is the externally defined interface used by Web browsers. The Web server can service the HTTP request or pass the request to the application server.

  • JDBC

    This interface is defined by Java and allows Java programs to access data within the supported databases.

  • SOAP

    The SOAP protocol is a lightweight protocol that supports the exchanged of information in a decentralized, distributed environment. SOAP is an XML-based product consisting of three parts:

    1. An envelope defining a framework for describing what is contained in a message and how it is processed.
    2. A set of encoding rules for expressing instances of application-defined data types.
    3. A convention for representing remote procedure calls and responses.
    4. SOAP is the key foundation for implementing Web services. SOAP is transported via HTTP.

    Installation of WebSphere Application Server, or its components, was not successful

    Does the installation process

    Installation hangs

    Check the wssetup.log. Does it show any errors? Scan the entire installation log for "error." "Total Errors: 0" at the end of the file indicates that the final step was successful, but the intermediate steps might not have completed.

    Look for errors indicating that the installation program was unable to read from a file, write or overwrite a file. File permission problems could have occurred.

    If wssetup.log does not display errors, or ends in mid-process with no errors, look at the command session from which the installation was launched. In a Windows NT environment, this means executing setup.exe from a DOS window instead of clicking it and clicking it again from within Windows NT Explorer. When the installation hangs, look at the window. Does it display an operating system error or Java exception?

    If it does not display an error, or the error message is not helpful for diagnosing the problem, record any messages displayed, and obtain help from IBM.


    Installation displays message dialog

    What kind of problem does the installation program message dialog indicate?

    Informix IDS_2000 has a load libc_r.a problem on an AIX 4.3.3 platform

    After installation, Informix IDS_2000 has a load libc_r.a problem on an AIX 4.3.3 platform even if the software installed without problems. If you run Informix commands such as oninit -ivy, onstat -l or onmode, you receive error messages. To avoid error messages, do one of the following:

    • Load the AIX driver using the System Management Interface Tool (SMIT).
    • At the AIX command prompt, enter the following command to ensure that asynchronous IO is available after the next reboot: mkdev -1 aio0 ; chdev -P -l aio0 -a autoconfig=available.


    Installation -insufficient disk space

    Does the system have the amount of disk space needed (as indicated by the dialog box)?

    Windows NT/2000:

    1. Open Windows NT/2000 Explorer.
    2. Right-click the drive where you are installing WebSphere Application Server.
    3. Select Properties to view the amount of space available.
    If the capacity is less than what is required, you cannot install WebSphere Application Server on this drive. If the capacity is sufficient, but the available space is not, delete enough files to provide the amount of space needed.

    UNIX

    • Use the df -k command to view the available space in your WebSphere Application Server file system. If necessary, contact the system administrator to increase the space.

    If you have sufficient disk space and are receiving an insufficient space message, obtain help from IBM.


    Insufficient software prerequisite level

    Look for requirements for supporting software in the InfoCenter article 1.3: Prerequisites.

    If you find that you have the appropriate prerequisites, obtain help from IBM.


    Installation finishes, but components are missing

    If installation is complete, but the product directories have not been created, files are missing, or service panel entries or Start menu icons have not been added, check the file wssetup.log.

    • Look for errors indicating that the installation program was unable to read from a file, write to a file, or overwrite a file. File permission problems could have occurred.

    If wssetup.log does not display errors, or ends in mid-process with no errors, look at the command session from which the installation was launched (in a Windows NT environment, this means executing setup.exe from a DOS window instead of double-clicking it from within Windows NT Explorer).

    When the installation hangs, look at the window -- does it display an operating system error or Java exception?

    If it does not display an error, or the error message is not helpful for diagnosing the problem, record any messages displayed, and obtain help from IBM.


    Installation - File permission problem

    Installation will be unsuccessful if:

    • The user ID under which the installation is running does not have authority to read the installation files or to write to (or overwrite files in) the target installation directory.
    • WebSphere Application Server and related processes have not been stopped before performing installation. Before installing WebSphere Application Server, stop the related processes. Here is how to stop the related processes:
      • Unix
        Stop all of the related processes identified by running the command ps -ef | grep java
      • Windows NT/2000
        Use the Task Manager to stop all of the processes named java, jre or jrew
    • Web servers and Web administrative servers should also be stopped
      • Windows NT/2000
        Stop the Web server and Web administrative server in the services panel
      • UNIX
        IHS can be stopped using the apachectl stop command. Other Web servers come with similar start and stop commands.

    The WebSphere administrative server will not start

    If the WebSphere Administrative server has never started, there might have been a problem with the installation. If any of the following conditions apply, check for installation problems:

    • The wssetup.log displays errors
    • The product root directory has not been created
    • The WebSphere Application Server Services panel entry or WebSphere Application Server Start menu items are missing (Windows NT/2000)

    Was the Nanny process unsuccessful in starting the administrative server? (UNIX)

    If the installation is complete, the following are possible reasons why the administrative server failed:

    • The user ID under which WebSphere Application Server is being started (specified at installation time) lacks sufficient authority.
      • Windows
        The user ID should have administrative-level authority. If the serving machine is on a Windows NT domain, the user ID should be defined (as an administrative ID) both on the local system and on the domain.
      • UNIX
        The user ID should have root-level authority. If WebSphere Application Server is running as a non-root ID, be sure to follow the appropriate setup steps.
    • During installation, the database specified for WebSphere Application Server to use as its repository has not been created. Review the InfoCenter article 2: Installation, and select the link for your platform and database.
    • The repository has not had its database manager started. If you do not know how to start the database, review the InfoCenter article 2: Installation, and select the link for your platform and database, or contact the database administrator.
    • The user ID and password specified at installation for access to WebSphere Application Server's database are incorrect. The values for these fields can be found in product root.They are encrypted, but can be temporarily overtyped with new values (they will be overwritten with encrypted values when WebSphere Application Server starts successfully).
    • An unsupported JDBC server configuration has been specified in the admin.config file. This is the case if the following error appears in the tracefile:

      F SMTL0026E: Failure to create a data source: COM.ibm.db2.jdbc.DB2Exception: [IBM][JDBC Driver] CLI0621E Unsupported JDBC Server configuration

      One known cause of this problem is having a repository database type of DB2, and specifying the com.ibm.ejs.sm.adminServer.dbserverName and com.ibm.ejs.sm.adminServer.dbportNumber properties in the admin.config file. In other words, using the "net" instead of "app" driver is not supported for DB2. The supported method of accessing a remote DB2 database as the WebSphere repository is to use the DB2 catalog utility to create a local alias for the remote database. The dbserverName and adminServer properties in the admin.config file must be left blank if the database type is DB2.

    Use jdbctest to check the availability of the WebSphere Application Server repository database.

    The jdbctest tool is available for download. Follow the instructions for downloading and installing the tool. When running the tool, use the same user ID and password to connect to your database as is specified in the admin.config file. Running jdbctest this way will indicate whether WebSphere Application Server can connect to its repository.

    If these steps do not reveal problems, the next step is to check the file <product root>/logs/tracefile for errors. If there is no tracefile file, or it is empty, try to diagnose the problem by launching the administrative server from the command line by executing adminservice.exe (Windows NT/2000) or startupServer.sh (UNIX) and look for errors displayed in the command window.

    In general, if the tracefile or command window does not display errors, and the message open for e-business is displayed, WebSphere Application Server is started and running.

    If open for e-business does not display, the tracefile or command window will display errors indicating repository database file permission or authority problems. If there are problems with the repository, review the steps for installation for your platform and database types. If WebSphere Application Server was able to create the file <product root>/logs/tracefile, try running the Log Analyzer for any warnings or errors that explain the problem.

    If the administrative server does not start (no "open for e-business"), and tracefile, command window and Log Analyzer display no errors, or the errors are not helpful, obtain help from IBM.


    Nanny process unsuccessful

    On UNIX systems, a separate process called "Nanny" launches the administrative server and attempts to launch it again if it fails. There is rarely a problem with the Nanny process, but the Nanny.trace file should be checked. If the file displays that the Nanny attempted to start the administrative server multiple times, this means that the Nanny process is healthy, but that the administrative server cannot start. Therefore, proceed with diagnosing the administrative server problem.

    If an error like

    E Administrative server creation Error creating new process. 001: Not owner

    is displayed, it might indicate that the correct procedure for running WebSphere Application Server as a non-root user on UNIX platforms has not been followed.


    Verifying security settings

    Here's where to look to verify security settings:

    • Administrative console Security Center
      • Global settings (authentication mechanism, enabled versus disabled)
      • Role-to-user bindings
      • Enterprise bean "run-as" mappings
    • Application Assembly Tool (AAT)
      • Web application security roles (in Web module "security roles" properties within enterprise application)
      • Enterprise bean security roles (enterprise bean module "security roles" properties within enterprise application)
      • Enterprise bean role references, if any (enterprise bean module "security roles" properties within the enterprise application)
      • Enterprise bean method permissions (enterprise bean module "security roles" properties within enterprise application)
      • Servlet security roles (Web module "security roles" properties within enterprise application)
      • Servlet role references, if any (Web module "security roles" properties within enterprise application)
      • Servlet security constraints (Web module "security constraints" properties within enterprise application)


    An application server will not start

    There are two main reasons an application server fails to start.

    1. A subcomponent of the application server, like an enterprise application or enterprise bean will not load or start, because it is configured improperly or depends on a file, database or other object which is missing or corrupted. This is indicated by one or more of the following symptoms:
      • Dialog boxes that pop up while the administrative server is attempting to start, with messages like, Command <server name>.start Sub-command error. Click Details in the dialog box displays a Java exception indicating a problem with a particular Web application or enterprise bean, like a missing EAR file.
      • Error messages signified by a red triangle in the bottom pane of the administrative console with text like Command <server name>.start Sub-command error, following the normal starting application server message. These messages will be followed by a Command <server name>.start Sub-command error message. Selecting an error message and then clicking Details displays a Java exception indicating a problem with a particular Web application, like a missing EAR file.
      • Messages in the tracefile like ADSM0104W: Failed to initialize a server: <server name>, followed by Java exceptions indicating problems with specific components, like com.ibm.ejs.sm.exception.OpException: file:product root/installedApps/Samples.ear does not exist. These exceptions will be followed by a message like, ActiveEJBServ W ADSM0104W: Failed to initialize a server.
    2. The application server is configured improperly so that it cannot start, for example, because an invalid Java option has been specified in its startup command.

    If there are no errors in the administrative console or tracefile indicating the cause of the problem, check to see if the application server's standard output or error file have been created. If so, check them for clues about why the application server did not start. Try running the Log Analyzer for any warnings or errors that explain the problem.

    If you cannot find any error messages, or the error messages are not helpful in diagnosing the problem, gather the errors and obtain help from IBM.


    A subcomponent of the application server like an enterprise application or enterprise bean will not load or start

    The following are reasons why a subcomponent fails to load:

    1. The EAR file which is installed in an enterprise application is missing. This is indicated by an error in the administrative console and tracefile like com.ibm.ejs.sm.exception.OpException: file:product_installation_root/installedApps/Samples.ear does not exist. This message corresponds to an existing enterprise application found under the enterprise applications folder in the administrative console. If this happens, copy the existing deployed EAR file to the indicated directory. If no deployed EAR file exists, or if you don't know if the EAR file is deployed or deployable, refer to installing enterprise applications.
    2. The database upon which a persistent (CMP or BMP) enterprise bean depends does not exist, or the application server does not have sufficient database authority to access it. This kind of problem is indicated in the application server's standard output file by messages beginning with Error creating CMP persister using data source... or Error starting CMP bean. These messages indicate both the name of the enterprise bean and and data source upon which it is based. When this happens, click the installed EJB modules administrative console to examine the properties of enterprise beans under the application server. Click on the bean's General and CMP data source tabs to verify the name of the enterprise beans data source and database user ID and password, and correct if necessary.


    If there are no errors in the administrative console or tracefile that indicate the cause of the problem, check if the application server's standard output or error file have been created. If so, check them for clues about why the application server did not start. You should also try running the Log Analyzer for any warnings or errors that explain the problem.

    If there are other errors relating to starting subcomponents of an application server, but they are not helpful or self-explanatory, obtain help from IBM.


    The application server is configured improperly

    An application server can be configured improperly in a way that will prevent it from starting. Here are the ways:

    • There is an invalid Java command-line argument. This can result in a Critical Error dialog box appearing when attempting to start an application server, with a detailed error of com.ibm.ejs.sm.exception.StaleActiveObjectInvocationException. Arguments to the Java command for an application server can be viewed by selecting the affected application server in the administrative console, selecting the JVM settings tab of its properties and then choosing Advanced JVM settings, and viewing the command line arguments field. The offending argument will appear in the application server's standard error file; search on "Unrecognized option:". Correct this field if necessary, apply the change, and then stop and restart the application server.
    • There is an invalid trace specification argument. From the application server's perspective, this is also an invalid command-line argument. See tracing WebSphere Application Server components for how to enable component tracing and for the correct syntax.

    Cannot access any servlet, JSP file, or HTML file from a browser

    If you are unable to access any Web resource from a browser, these are the possible causes:

    • There is a problem with the Web server. This is usually easy to detect. If you cannot see the welcome page of the HTTP server (entering a URL of "http://<server name>"), this is the case.
      • The physical Web server is down or not available.
        Can you see that the machine is running, or run ping <hostname> from the machine on which your browser is running, to ensure that it is available?
        If the machine is started and running, but you cannot ping the machine, there might be network configuration or firewall issues that prevent the browsing machine from connecting to the Web server. Contact the network administrator or system administrator.
      • The Web server and WebSphere Application Server are running on separate machines, but cannot communicate with each other.
      • The Web server used to serve WebSphere Application Server-bound requests has not been started. On Windows NT/2000, look in Control Panel > Services to see if the service has been started. On UNIX, look for Web serving processes by issuing the command ps -ef | grep | http. There should be one or more processes displayed as output.
      • If the Web server is running, and the machine can be pinged, but you cannot see the welcome page from a browser, or if you cannot get the Web server to start, contact the vendor of the Web server for help. If the Web server is IBM HTTP Server, obtain help from IBM.
    • The plug-in has not been properly installed or configured, causing the Web server communicating improperly with WebSphere Application Server. This is likely if the browser displays a message like The page cannot be found or The requested URL /<app context name>/<servlet or JSP file name> was not found on this server.
    • The application server in which the servlet has been installed was not started, or cannot start. This can be the case if you are seeing a message like Internal Server Error - The server encountered an internal error or misconfiguration and was unable to complete your request in the browser. Check the administrative console and verify that the resource's application server state is indicated by a green "+" next to it under nodes > <node name> > <Application Servers> > <app server name>.
    • The enterprise application, Web module, or Web resource cannot be loaded for service by WebSphere Application Server. This is indicated by an error in the browser like Error 500: Failed to load target servlet [<servlet name>] , and an error in the WebSphere Application Server console like Servlet Error (Root + 1)-[<servlet name>]: Failed to load servlet: javax.servlet.ServletException: Servlet [<servlet name>]: Could not find required servlet class - <classname>.class.

    If none of these conditions apply, examine the following files for clues:

    • The Web server error log (logs/error.log in the Apache or IHS directory structure)
    • The plug-in log file (name and location specified in the file product root/config/plugin-cfg.xml, defaults to native.log)

    Also, try accessing your resource directly from WebSphere Application Server's built-in HTTP server, bypassing the production Web server. If this is successful, the problem is with the Web server or the Web server's WebSphere Application Server plug-in.

    If you cannot view the resource directly from WebSphere's HTTP server, there is a problem loading or serving the Web resource.



    The plug-in has not been properly installed or configured

    This could be the case if any of the following are true:

    • There were error dialog boxes during the installation of the Web server plug-in
    • Errors indicating plug-in-related installation problems in wssetup.log
    • The Web server's own plug-in configuration file (httpd.conf for Apache or IHS, obj.conf for iPlanet or Netscape) displays no modifications after the installation.
    • There is no plugin-cfg.xml file in the product root/config directory of the Web server machine
    • The Web server's own error log, like Apache's /logs/error.log), displays the Web server accessing its own directory structure to find resources, instead of forwarding the request to WebSphere Application Server (for example, "File does not exist: f:/ibm http server/htdocs/servlet/snoop")

    If this is true, repeat the procedure for installing the plug-in. If the Web server is remote (not on the same machine as WebSphere Application Server itself) make sure you are installing the plug-in on the Web server machine, and then copy the plugin-cfg.xml file from the WebSphere Application Server server machine to the Web server machine.

    If the plug-in is properly installed, these are the next steps:

    If these steps do not yield results, gather the HTTP server's error.log, the plug-in log file (if any), and the plugin-cfg.xml file, and obtain help from IBM.


    Cannot access a specific servlet, JSP file or HTML file from a browser

    When a specific servlet, JSP file or HTML file cannot be accessed from a browser, the first question to ask is, what is the scope of the problem?

    If none of these resolve the problem, look for errors in the following locations:

    If none of these steps resolve the problem, or yield error messages or warnings which are not helpful, obtain help from IBM.



    Cannot start the administrative console

    If you attempt to start the administrative client, and the interface is not displayed, or if you see a dialog box or window briefly and then shuts down, verify these items:

    • If you are running the console remotely (not on the same machine as the WebSphere administrative server)
      • Do you have TCP/IP connectivity between the machine that is running the console and the machine that is running WebSphere Application Server. Can you run the ping <hostname> command on the console machine, where <hostname> is the IP address or hostname of the WebSphere Application Server serving machine? If not:
        • The WebSphere Application Server machine might be down
        • The console machine might not have access to the server machine If so, contact the network administrator and ask these questions:
          • What is the server machine's IP address or hostname on the network's name server?
          • Is there is a firewall between the two machines? If so, is the WebSphere Application Server bootstrap port (default 900) opened in the firewall?
      • Are you accessing the administrative console indirectly through a display export utility like Hummingbird Exceed? If so, install the administrative client locally (you can install just this piece of WebSphere Application Server) and launch it against the server by executing the command adminclient <remote-host-name>.
      • What happens if the console is run from a different machine? If that works, there is an issue particular to the failing machine, like network access to the WebSphere Application Server machine.
    • WebSphere Application Server might not be listening for client requests on the default port (900). Ask the WebSphere Application Server administrator if the bootstrap port has been changed from the default of 900.
    • Is the version of WebSphere Application Server the same as the version of the administrative client? Different versions, revisions, as well as different fix pack levels between the two, can cause failure. Typically, this results in a low-level Java exception like ClassCastException or NullPointerException in the window from which the client was launched.
    • If you Cannot access the administrative server after enabling security, ask these questions:
      • Did a log-in prompt display when the console was launched? If not, the security was enabled since the console was installed, and the console does not know that the server is secured. This can happen, for example, if the console is running remotely. Check the file product root/properties/sas.client.props on the client machine if the client machine is different from the server. Ensure the following properties match the values in sas.server.props on the serving machine:
        • com.ibm.CORBA.securityEnabled
        • com.ibm.CORBA.loginUserid
        • com.ibm.CORBA.loginPassword
      • If a log-in challenge appeared, but the user ID and password were rejected, check the file product root/properties/sas.client.props on the client machine, if different from the server. Ensure the following properties match the values in sas.server.props on the serving machine:
        • com.ibm.CORBA.loginUserid
        • com.ibm.CORBA.loginPassword

    If none of these tips help:

    • Look at the window from which the console was launched. There might be errors or exceptions helping to explain the cause of the problem.
    • Look at WebSphere Application Server product root/logs/tracefile file. If the console program contacted the server and was rejected, there might be related errors.
    • Run the Log Analyzer on the server machine and look for warnings and errors

    If none of these steps help, gather any error messages and dialogs from the client, Log Analyzer, and tracefile file, and obtain help from IBM.


    My servlet or JSP file cannot call or connect to third party software

    If the servlet or JSP file uses classes provided by a third party vendor, or connects with a running process external to WebSphere Application Server such as a database or CORBA server, the following are potential causes of problems:

    • The JAR file or directory containing the software's supporting classes is not on the servlet or JSP files classpath. This is indicated by Missing class errors or java.lang.classNotFound exceptions in the application server's standard error or output files. These files also indicate the missing class. Ensure supporting classes are provided to the servlet or JSP file.
    • The third party software depends on a release of the Java JDK that is not compatible with WebSphere Application Server JDK. If this happens,low-level errors or exceptions like java.lang.ClassCastException might occur. Verify with the third party software vendor or its documentation that the software is compatible with the WebSphere Application Server JDK level. See the InfoCenter article 1.3: Prerequisites for more information regarding prerequisite information.

    A servlet or JSP file displays an error or Java exception instead of the correct output

    What is the scope of the problem?

    • If calling a servlet or JSP file results only in an error message in the browser, look at the hints for "Cannot access a particular servlet from a browser".
    • If the servlet is functioning, but parts of the output are missing (for example, the image files do not display), then the servlet links to components incorrectly, or the subcomponents are missing or in the wrong directory. Check the resource references to other resources.
      • Do the files they refer to exist?
      • Are the references correct?
      • References that begin with "/" start from the document root of the current Web application. If the reference does not start with a "/", the current path of the host resource is prepended to the called resource's URI.
    • If the servlet is functioning, but its output does not appear to be correct (for example, the output does not appear to match a user's search criteria), then follow the steps for debugging a servlet or JSP file.

    If none of these steps help in resolving the problem, gather the Web server error and access logs, WebSphere Application Server's tracefile, the application server's standard error and output file, and the native.log file, and obtain help from IBM.


    JSP source code file shown by the Web server


    If you share the document root of the WebSphere Application Server within the Web server document root, a security exposure can result as the Web server might display the JSP source file as plain text.

    You can use the WebSphere Web server plug-in set of rules to determine whether a given request will be handled by the WebSphere Application Server. When an incoming request fails to match those rules, the Web server plug-in returns control to the Web server so that the Web server can fulfill the request. In this case, the unknown host header causes the Web server plug-in to return control to the Web server because the rules do not indicate that the WebSphere Application Server should handle it. Therefore, the Web server looks for the request in the Web server document root. Since the JSP source file is stored in the document root of the Web server, the Web server finds the file and displays it as plain text.

    To fix this problem, move the WebSphere Application Server JSP source file outside of the Web server document root. Then, when this request comes in with the unknown host header, the plug-in returns control to the Web server and the JSP source file is not found in the document root. Therefore, the Web server returns a 404 File Not Found error rather than the JSP source file.

    Unauthorized users can access servlet, JSP file, or HTML file when security is enabled


    If unauthorized users can access a secured resource, these are the steps to follow:

    • Ensure that all of the steps necessary to secure the resource have been followed. Enabling security in the administrative console is not enough. In summary, these steps are:
      • Enabling security and setting global security properties in the administrative console's Security Center
      • Defining security roles for the enterprise application in the AAT
      • Mapping security roles to security role references, if any, established by enterprise beans or servlet provider in the AAT
      • Mapping enterprise bean methods to security roles, if any, in the AAT
      • Creating security constraints for servlets in the AAT
      • Mapping security roles to security constraints in the AAT
      • Create a Web resource collection under the constraint to map URLs and methods to the constraint
      • Defining "run-as" roles for enterprise beans at enterprise application installation time or in the administrative console's Security Center.
      • Map roles to actual user or group IDs, at enterprise application installation time or in the administrative console's Security Center.
    • If security has been set up, verify the settings. Specifically, for a servlet, verify that:
      • At least one security role has been created in the Web module the affected servlet belongs in
      • A security constraint has been created in the Web module where the affected servlet belongs, which contains the role
      • A Web resource collection has been created in the security constraints, which contains the affected servlet's URL pattern and methods
      • Verify that access to a resource's role has not been granted to all users in the Security Center in the administrative console.
      • If more than one logical URL name for a resource has been defined (for example, the same physical servlet MyServlet.class can be accessed as "http://<hostname>/myapp/servlet/MyServlet" and "http://<hostname>/myapp/servlet/MyServlet2") make sure that all URLs are mapped to a constraint in the AAT.
    • The process for verifying access to a JSP file is the same as that for a servlet
    • HTML pages not served by WebSphere Application Server, Advanced Edition 4.0.x, cannot be secured by WebSphere Application Server. If an HTML file is to be secured, the URIs and the resources must be packaged in a Web application archive.
    • If the unauthorized access is to an enterprise bean, also verify the settings. Specifically, verify that:
      • At least one security role was created in the enterprise bean module where the affected enterprise bean belongs
      • A method permission object in the enterprise bean module containing the affected enterprise bean, was created in the security constraints. The security constraints maps the security role to the affected enterprise bean's remote and home interface methods.
      • Verify that access to the enterprise bean's role has not been granted to the authorized users, groups, "Everyone", or "All authenticated users" in the Security Center in the administrative console.
      • If unauthorized access to an enterprise bean occurs when called from another enterprise bean (such as, by a session enterprise bean, which is a client of a CMP bean), ensure that the client enterprise bean has its "run-as" identity set appropriately.

    If none of these steps reveal the source of the unauthorized access, run the Log Analyzer.

    If the source of problem is still not apparent, gather the following files:

    and obtain help from IBM.


    Authorized users cannot access the servlet, JSP file, or HTML file when security is enabled

    If Authorized users (that is, users entering valid IDs and passwords) cannot access a secured resource, follow these tips:

    • Ensure all of the steps necessary to secure the resource have been followed. Enabling security in the administrative console is not enough. In summary, these steps are:
      • Enabling security and setting global security properties in the administrative console's Security Center
      • Defining security roles for the enterprise application in the AAT
      • Mapping security roles to security role references, if any, established by enterprise bean or servlet provider, in the AAT
      • Mapping enterprise bean methods to security roles, if any, in the AAT
      • Creating security constraints for servlets in the AAT
      • Mapping security roles to security constraints in the AAT
      • Create a Web resource collection under the constraint to map URLs and methods to the constraint
      • Defining "run-as" roles for enterprise beans when the enterprise application is installed or in the administrative console's Security Center.
      • Map roles to actual user or group IDs when the enterprise application is installed or in the administrative console's Security Center.
    • If security has been set up, verify the settings. Specifically, for a servlet, verify that:
      • At least one security role has been created in the Web module where the affected servlet belongs
      • A security constraint has been created in the Web module where the affected servlet belongs, in which contains the role
      • A Web resource collection has been created in the security constraints which contains the affected servlet's URL pattern and methods
      • Verify that access to a resource's role has been granted to the affected user, a group the user is in, to "Everyone" or to "All authenticated users" in the Security Center in the administrative console
      • If more than one logical URL name for a resource has been defined (such as, the same physical servlet MyServlet.class can be accessed as "http://<hostname>/myapp/servlet/MyServlet" and "http://<hostname>/myapp/servlet/MyServlet2") make sure that all URLs are mapped to a constraint in the AAT
    • The process for verifying access to a JSP file is the same as that for a servlet
    • If the unauthorized access is to an enterprise bean, also verify the settings. Specifically, verify that:
      • At least one security role has been created in the enterprise bean module where the affected enterprise bean belongs
      • A method permission object in the enterprise bean module, which contains the affected enterprise bean, has been created in the security constraints. The security constraints map the security role to the affected enterprise bean's remote and home interface methods.
      • Verify that access to the enterprise beans role has been granted to the authorized user ID's or groups, or to "Everyone", or to "All authenticated users" in the Security Center in the administrative console
      • If unauthorized access of an enterprise bean occurs when it is called from another enterprise bean (such as, by a session enterprise bean which is a client of a CMP bean), ensure that the client enterprise bean does not have its "run-as" identity set inappropriately
    • Look for authorization failed and authentication failed-type messages in the tracefile. These will display what user ID is being used to authenticate and which resource it is being checked against when access fails.
      • Authorization failures occur when WebSphere Application Server finds the user ID in its system, but it is not authorized to access the resource
      • Authentication failures occur when WebSphere Application Server does not find the user ID and password in its registry (operating system, LTPA server, or pluggable registry). This can happen because:
        • The user ID is not in the system, because it is missing or a mistyped or intentionally bogus user ID was entered
        • An invalid password was entered by the user
        • The settings for accessing and searching the registry are invalid or too narrow

    If none of these steps reveal the source of the access problem, run the Log Analyzer.

    If the source of problem is still not apparent, gather the following files:

    and obtain help from IBM.


    Users have access problems even after entering valid log-in information



    If users can successfully access a secured Web session, but cannot access another page in the same Web session, here are some tips:

    • Are the users going to a page in the same Web application that is not secured? If the user encounters an unsecured resource in their navigation path within the same Web application, the credentials are lost. The resolution is to secure everything that the user in the Web application might reasonably access in a session.
    • If the application is cloned across multiple servers, ensure that single sign-on is enabled in the administrative console's Security Center. Also, make sure the domain and realm fields are the same on all servers.
    • If a host's short name is being used to access the affected resources, try using the full Internet domain name in the URL.

    If none of these steps reveal the source of the problem, run the Log Analyzer.

    If the source of problem is still not apparent, gather the following files:

    and obtain help from IBM.


    Form-based login is not working

    What kind of problem are you having with form log-in?

    • If the user is not redirected to the form when accessing a secured resource:
      • Check the tips for unauthorized access problems
      • Temporarily switch from form log-in to basic challenge in the administrative console's Security Center. If basic challenge works, the resource has been secured correctly, but there is something wrong with how the form log-in implemented.
      • Ensure the form's URI as entered in the Security Center is correct
      • If the user is entering the WebSphere Application Server's short name, try entering the complete domain name in the browser when accessing the secured URI
    • If the user is directed to the form, but logging in with a valid user Id and password does not work (for example, a valid user is not granted access to the resource)

    If none of these steps reveal the source of the problem, run the Log Analyzer.

    If the source of problem is still not apparent, gather the following files:

    and obtain help from IBM.


    Errors are displayed after configuring general security

    If you are unable to save the general security settings in the Security Center of the WebSphere Application Server console, it is probably because the values are incorrectly specified on the Authentication tab. The values direct WebSphere Application Server on how to communicate with the system (operating system, LDAP server, or classes that you provide), which then verifies user IDs and passwords. For details on these fields, see help on global security settings.

    If you are using LDAP, verify:

    • The hostname has connectivity to the WebSphere Application Server server machine (for example, the hostname can be pinged from a command window)
    • The port is the one the LDAP server is listening on (usually 389)
    • The Security Server ID and password are valid on the target LDAP server
    • The user filter is correct for the way that the Security Server ID and other user IDs are stored in the system (for example, if a clause in the filter specifies "inetOrgPerson:uid", that users are stored in the LDAP server with object type of inetOrgPerson, and that the "uid" field is filled in)
    • The Bind Distinguished Name and password are valid values for binding to the LDAP server. Verify this by manually binding to the LDAP server using its own administrative GUI, or by running the "ldapsearch" utility provided with LDAP servers.

    If you are using the local operating system as your user registry system, verify that:

    • The user ID has root-type authority (UNIX) or
    • The account is a member of the administrators group and must have the rights to "Log on as a service" and "Act as part of the operating system."(Windows NT/2000) If you are using a Windows NT domain, the user ID must be an administrator in the Windows NT domain.

    If you are using the pluggable registry, verify that:

    • The class used to implement the CustomRegistry interface is on Classpath

    If none of these steps help, try to save the global security settings, then run the Log Analyzer.

    If the source of problem is still not apparent, gather the following files:

    and obtain help from IBM.


    When mapping users to security roles, the lists of users and groups are empty


    If the list of available users and groups is empty in the Security Center, ensure that:

    • If you are using LDAP server as the user registry, it is started and running
    • The filter settings specifying object type and attribute name, match the way users are stored in the LDAP server
    • The way you search for users ("*") is valid when plugged into the filter's placeholder ("%v"). Verify this by using the ldapsearch utility of the LDAP server.
    • The Bind Domain Name and password are corrected. Verify this by using the ldapsearch utility of the LDAP server.
    • The Base Domain Name is correct and at a level in the LDAP directory structure where it contains the user IDs that you want to select from. Verify this by using the ldapsearch utility of the LDAP server.
    • If you are using the operating system as your registry, verify that:
      • The user ID has root-type authority (UNIX) or
      • The account is a member of the administrators group and must have the rights to "Log on as a service" and "Act as part of the operating system." (Windows NT/2000) If the machine is a member of an Windows NT domain, the user ID must also be an administrator in the Windows NT domain.
    • If you are using a pluggable registry, verify the class used to implement the CustomRegistry interface is on WebSphere Application Server's classpath
    • If none of these steps help, try to search for users, then run the Log Analyzer.

    If the source of problem is still not apparent, gather the following files:

    and obtain help from IBM.


    Modifying and recompiling an existing servlet

    Suppose you want to add trace code, a main() method, or make other changes to an existing servlet source and recompile and deploy it. Here are some tips:

    If you have trouble finding the servlet source (Java) file, follow the procedure for finding the servlet .class file. Typically, if the Java file exists, it will reside in the same EAR file as the class file. Then, an unzip utility or the JAR command can be used to extract the Java file.

    The EARExpander tool is also available to expand or collapse and enterprise application. This tool will unjar all various archives in an EAR file all at once versus individually. The tool can be invoked as \bin\EARExpander.bat/sh.


    Recreating run time classpath


    You should try to reconstruct the classpath under which the servlet runs when recompiling the servlet. If there are problems with the classpath (like missing supporting classes), repeating the compile process might reveal the cause. The classpath setting can be duplicated at compile time by using the -extdirs <one-or-more-directories> option of the javac command, and giving it the same value as the -Dws.ext.dirs property in the admin.config file. The -extdirs option takes a list of directories. Subdirectories and JAR files in the -extdirs directories are automatically added to the classpath. You do not need to add them individually. Any supporting JAR files specific to the application are added by setting up a classpath environment variable, or by adding them to a temporary directory and adding the directory to the -extdirs option when you run javac. If you get an error indicating that -extdirs is not a valid javac option, you are probably picking up an earlier javac version. Make sure to run Java and javac from the [Websphere install directory] /java/bin directory. For simple Java programs, it might be enough to add -extdirs [webSphere install dir]/lib to the javac command.


    A servlet or JSP file displays an error or Java exception instead of the correct output

    The following are techniques for diagnosing problems in a servlet or JSP file. These techniques are recommended for use in a test environment only.

    1. Output statements can be added to the doGet(), doPost() or service() method of the servlet Java class, or within the Java code blocks of a JSP file. System.out.println() and System.err.println() statements write to the containing application server's standard output and standard error files, respectively. The String passed to these statements can display variable contents or indicate a certain method has been reached. This requires updating the servlet source with the print statements, recompiling the servlet and restarting its application server.
    2. The servlet can be enhanced to run as a standalone program. To do this, create a public method main() in the servlet Java file. The main() method will have logic copied from the servlet's existing doGet(), doPost() or service() method. After the class is recompiled, it can be executed from a command line using the command java <servlet-class-name>. The Java command installed with WebSphere Application Server (in product root/java/bin>)can be used for this purpose. If the servlet can run as a main program,the problem is related to how it is deployed in WebSphere Application Server. This technique requires an update to the servlet source to add the main()method, and a recompilation of the servlet to pick up the change. If the problem involves a JSP file, see below for how to get it in servlet form.
    3. The OLT/Debugger tool, provided with WebSphere Application Server, Advanced Edition, can be used to step into a running servlet to examine return codes and variables during execution. In order to do this, the servlet class file must be compiled with the -g option, if it was not originally created this way, and the application server must be set up to communicate with the OLT client program. For details, see the documentation on the OLT and Debugger tool.
    4. If the problem resides in a JSP file, the servlet source created from the JSP file by WebSphere Application Server can be captured using the "keepgenerated" option. After this has been done, the new Java file can be deployed and debugged as a servlet.

    All of these procedures, (with the exception of number three, if the source file was already created with the -g option), require the servlet source file to be recompiled. The Java compiler utility installed in product root/java/bin can be used for this purpose.

    Also, the classpath environment variable under which the servlet has been running should be duplicated when the servlet is compiled.

    Typically, the servlet source file, <servletclassname>.java, if supplied by the developer, will be found in the same EAR file as the servlet class file. To find it, follow the procedure for verifying a servlet class file.

    Once you have recompiled the servlet, unless you are running it as a standalone Java program, follow the procedure for reloading a resource into WebSphere Application Server.

    If you have converted it into a main program, launch it using the >product root/java/bin/java <javaclass> command. Again, for a good test, replicate the WebSphere Application Server classpath under which the servlet ran.


    Verifying the servlet URI, class file and classpath

    To determine if the URI you are entering matches a servlet served by WebSphere Application Server and that the class file is in the right place, check the following:

    A servlet is contained within a Web application, stored as a .war (Web application archive). The Web application is logically contained in an enterprise application, which is physically stored in an EAR file.

    • Start the AAT, and use File > Menu to open the EAR file, which contains the Web application and servlet. (If you don't know which EAR file contains the servlet's Web application, use the administrative console to examine the Web modules under each enterprise application. If you don't know the enterprise application, EAR file, or Web application containing the servlet, step through all the EAR files in the AAT until you find the right one.)
    • In the AAT, expand the enterprise application's Web modules
    • Under Web modules, select the Web application containing the servlet. In the properties on the right, look at the "context root" attribute. This field corresponds to the "application path" attribute of earlier versions of WebSphere Application Server. All the resources served by this Web application must start with this path in the URL.
    • The classpath field represents JAR file(s) containing any supporting classes needed by the application's resources, like enterprise bean client classes if a servlet is an enterprise bean client.
    • Now expand the application's Web Components, then select the servlet you are trying to access. The component name reflects the logical name of the resource as entered in the URL. The servlet class name represents the program WebSphere Application Server needs to load when the URL is requested.
    • If the servlet has been added to the application by using the AAT, its class or JAR file does not need to be explicitly added to the Web application's classpath.
    • When an enterprise application is installed, its EAR file and the WAR files it contains are physically expanded into a directory named after the EAR file. Usually you will find this directory under the product root/installedApps directory. Servlet classes exist in the <earname>.ear\<warname>.war\WEB-INF\classes directory or in a JAR file contained within the WEB-INF\lib directory. These items are automatically included in the Web applications classpath by the Web container.

    Example: If the Web application's context root is /webapp/examples, and it has a servlet whose component name is "ping," and whose class name is "PingServlet", then:

    • The URL for accessing the servlet would be http://<hostname>/webapp/examples/ping, and
      WebSphere Application Server would attempt to find and load the class PingServlet the first time it is invoked, or when the containing application server is started, if "load on startup" is checked.


    Accessing the resource directly from WebSphere Application Server's built-in HTTP server

    It can be useful to try accessing a servlet or other Web resource directly through an application server's built-in HTTP server, bypassing the production Web server. If successful, the problems serving the resource are related to the Web server or to its WebSphere Application Server plug-in, which it uses to communicate with WebSphere Application Server.

    If unsuccessful, WebSphere Application Server has a problem loading or serving the resource, like a missing class file.

    To access a resource through an application server's HTTP server, specify the application server's HTTP listener port in the URI. For example, if the resource you are looking for is normally accessed as "http://myhostname.mydomain.com/servlet/snoop", try instead "http://myhostname.mydomain.com:NNNN/servlet/snoop", where NNNN is the port number used by the application server under which the enterprise application that contains snoop is installed.

    To find the right port number, look in the product root/config/plugin-cfg.xml file. There should be a block similar to (this example uses an application server named "default_server"):

    <!-- Server groups provide a mechanism of grouping servers together. -->
    <ServerGroup Name="default_group">
    <Server Name="default_server">
    <!-- The transport defines the hostname and port value that the Web server
    plug-in will use to communicate with the application server. -->
    <Transport Hostname="localhost" Port="9080" Protocol="http"/>
    </Server>
    </ServerGroup>

    The port attribute of the <Transport> block indicates the HTTP port of its application server, in this case 9080.


    Adding and verifying supporting classes or JAR files to a Web application's classpath

    If an application server generated a java.lang.ClassNotFound exception in trying to load a servlet, and the indicated class is not the servlet, a supporting class or JAR file is missing from the application server's classpath.

    To view and update the classpath, use the AAT.

    • Start the AAT, and use File > Menu to open the EAR file containing the Web application which has the servlet.
    • In the AAT, expand the enterprise application's Web modules.
    • Under Web modules, select the Web application containing the servlet.
      The classpath field represents JAR file(s) containing any supporting classes needed by the application's resources, like EJB client classes if a servlet is an EJB client. Add any needed JAR files, or directories containing individual classes here.

    Make sure WebSphere Application Server's administrative server is started and running

    The best way to examine the state of the WebSphere Application Server administrative process is to start the administrative console. If you cannot access the console, any of the following steps can be used to verify that WebSphere Application Server is working:

    • Access a resource served by WebSphere Application Server, such as the sample servlet <hostname/servlet/snoop>. If the resource returns a Web page, WebSphere Application Server is working. If a Web page is not returned, this does not necessarily mean WebSphere Application Server is not running; any number of factors can cause a servlet not to return output.
    • Use the ps -ef | grep AdminServer command (UNIX only). If it returns a process, WebSphere Application Server (or some other process named AdminServer) is running.
      Run a WebSphere Application Server utility like WSCP or xmlconfig. These utilities are WebSphere Application Server client applications. They will only work if WebSphere Application Server is started and running. It is mandatory that you execute a task because entering the command and getting the usage information does not initiate contact with the server.
    • Check to see if the administrative server is started and running by looking at the Services panel (Windows platforms only) to see if the status "started"

    HTTP sessions are not created, or are dropped between Web requests in a session

    To view the sessions settings for an application server, see the InfoCenter article 6.6.11: Administering HTTP session support.

    If HTTP sessions are not created, or appear to get dropped between one Web request and another within the same session (multiple requests within a short period of time from the same browser on the same client machine), here are some possible causes:

    • In the sessions settings for the application server, is sessions management enabled?
    • If the mechanism for storing and retrieving session ID is cookies, are cookies enabled on the affected browser?
    • If the mechanism for storing and retrieving session ID is URL rewriting, are there any static HTML pages in the user's navigation path? If so, the session will get dropped since WebSphere Application Server cannot update the URL link that the user clicked, so that the next page will include the session ID.
    • Is data getting dropped when the user goes from a page in one Web application to another? With WebSphere Application Server, Advanced Edition 4.0.x and later, because of the J2EE specification, sessions are not shared across Web applications.
    • Are persistent sessions turned on in the application server? If so, were correct values given for the data source, user ID and password? Is the specified database started and running?
    • Is the application or some of its components cloned across multiple servers? If so, has session persistence been enabled?
    • Is security enabled? If so, is the user doing anything to lose their security log-in information before going to the page where session data is dropped (like visiting a page that is not secured)?

      If you are using both session management and WebSphere Application Server security, make sure that all pages in your Web application are secured.

    Try using the snoop sample servlet to diagnose the problem. Snoop displays all the elements in the current HTTPSession, including session ID. You can jump to snoop after a session is started, then go back to it in between other pages to see when the session ID changes or has been dropped. This technique will work if the snoop servlet is in the same Web application as your application. If necessary, deploy the snoop servlet (look for SnoopServlet.class in product_installation_root/installedApps/sampleApp.ear/default_app.war/WEB-INF/classes).

    Try using the Log Analyzer to see if there are any relevant errors or warnings. Files to look at are:
    The application server standard output and error files
    The plug-in's native.log file
    The Web server's error and access log files

    If you still cannot track down the problem, gather these files and obtain help from IBM.



Verifying the Web server's configuration file

See the InfoCenter article 6.6.45: Administering WebSphere plug-ins for Web servers for more information on verifying the Web server's configuration file.


Determining the version of WebSphere Application Server


The easiest way to determine what version of WebSphere Application Server you have installed is to launch the administrative console, then click the Help menu, and select About.

Alternatively, you can browse the file, product root/properties/com/ibm/websphere/product.xml and look for the block named "version".


Verifying the classpath for a servlet, JSP file, enterprise bean or supporting classes

The following problems are indications that the right class or classes are not available to your servlet, JSP file or enterprise bean:
  • Missing class error or classNotFoundException

    These errors might display in the administrative console, browser output, Log Analyzer, or application server's standard output or error file after the application server tries to load or execute a resource, or compile a JSP file. This indicates that a needed application server is missing.

  • No such method error or classCastException

    These errors might display in the administrative console, browser output, Log Analyzer, or application server's standard output or error file after the class tries to load or execute a resource, or compile a JSP file. This indicates that the wrong version of a supporting class is being loaded.

When this happens:
  1. Search for the class indicated in the error to verify that it exists somewhere in WebSphere Application Server's directory, and to determine if there are more than one versions of the same class.
    • In Windows NT/2000, open the Windows NT/2000 Explorer and select the product root.
      • Use the Tools > Find > Files or Folders menu option to search for <missing class name>.class
      • Also, search for occurrences of the class inside a JAR file by using the Tools > Find > Files or Folders menu option. Search for all files named *.jar, containing text (Advanced tab if Windows NT/2000) <missing class name>.class
    • On UNIX systems, open a command window in the WebSphere Application Server installation directory (or the root directory if there is any chance that the class might exist elsewhere).
      • Search for occurrences of the missing class by executing find . -name <missing class name>.class -print
      • To find JAR files containing the class, create a command or shell script that recursively extracts the contents of each JAR file and searches the results for the missing class. The following sample, which searches JAR files for a class file called Policy.class can be saved and executed on a UNIX system:find ./ -type f -name '*jar'|
        while read jfile
        do
        jar vtf $jfile|grep Policy.class
        if [ "$?" = "0" ]
        then
        print found "Policy.class in $jfile"
        fi
        done
  2. If the class cannot be found, contact the enterprise bean, servlet or JSP file provider and ask about the missing class.
  3. If the class exists, but is not getting loaded, or the wrong version is getting loaded, review the information on setting classpaths and on classloaders. Compare them to your configuration. Use the Application Assembly Tool to add the supporting class directory or JAR file to the dependent Web application or enterprise bean container.

An error occurs generating deployed code for an enterprise bean

If you receive error messages when trying to generate deployed code for an enterprise bean in the AAT, here are some things to check:
  • Does the input JAR file contain a specification level 1.0 enterprise bean? One way to tell is if the JAR file does not contain the files required to deploy a 1.1 enterprise bean:
    • ejb-jar.xml
    • ibm-ejb-jar-ext.xmi
    • ibm-ejb-jar-bnd.xmi
    If this is the case, convert the enterprise bean to specification level 1.1.
  • Is the enterprise bean class part of a Java package? In other words, does its definition include a package statement class (you might need to verify this with the developer or provider of the enterprise bean)? If not, its class must be changed to be part of a package. This is to ensure uniqueness of class names across enterprise beans. This is required in WebSphere Application Server, Advanced Edition 4.0.x.
If these tips don't resolve the problem, gather any error messages displayed by the AAT, and obtain help from IBM.

An error occurs installing an enterprise application

If you receive errors in the administrative console while installing an enterprise application, here are some items to check:
  • Does the enterprise application contain persistent (CMP or BMP) enterprise beans? If so, has the data source referenced on the Bindings tab of the enterprise bean's properties been defined?
  • Is the enterprise application you are installing already installed? If so (you have made changes to the deployed code and are reinstalling it), uninstall the enterprise application before reinstalling it.
  • Is the EAR file that represents the application in a read-only state? If so, change it to write state and install the application again.
Run the Log Analyzer for clues as to why the client application is failing.

If these tips don't resolve the problem, gather the tracefile, the activity log, and the standard output and error files from the application server into which you are trying to install the application, and obtain help from IBM.


Converting 1.0 enterprise beans JAR files to 1.1

See the InfoCenter article 6.3: Assembling applications and generating deployment code to review converting enterprise beans JAR files.

My servlet, JSP file or session enterprise bean cannot connect to a third-party software package

If your servlet, JSP file or session enterprise bean cannot access a third-party software package, here are some tips:
  • Have you made client classes provided by the vendor, available to the servlet, enterprise bean or JSP file? For example, if the client process is a servlet or JSP file, are the client class files or JAR added to the classpath property of the containing Web module in the AAT?
  • Are the client class files and the third party software J2RE 1.3 compatible?
  • Is the third party software running on a different physical from WebSphere? If so, can the WebSphere server communicate with the the other software's machine? For example, can you run the ping <remote server's hostname> command from one machine and get a valid response? If not, contact the network administrator because there might be name server or firewall issues involved.
  • It can be useful to run your servlet, JSP file or enterprise bean as a standalone application, outside of WebSphere Application Server, to isolate the problem.
Run the Log Analyzer for clues as to why the client application is failing.

If these tips don't resolve the problem, gather the tracefile, the activity log, and the standard output and error files from the application server containing the resource which is trying to connect to third-party software, and obtain help from IBM.


Secured Socket Layer (SSL) encrypted requests ("https://...") do not work

If clients cannot make SSL-encrypted requests or receive SSL-encrypted responses, here are some things to check:

  • Does basic SSL communication work between clients and your Web server, independent from WebSphere Application Server? In other words, can you access the welcome page of your Web server using SSL (with a URL of "https://[hostname]")? If not, check the Web server documentation on how to configure the Web server for SSL. Some Web servers require configuration changes for SSL.
    •  The IBM HTTP Server (IHS) does require changes to be made to its httpd.conf file. Documentation can be found at http://www.ibm.com/software/webservers/httpservers/doc/v1312/ihsfaq1.html#sslconf.
  • Have you added aliases to the virtual host in the administrative console to include SSL-type "https://" requests?
    • In the administrative console, select Virtual Hosts from the topology, then select each virtual host from which you intend to serve SSL requests
    • On the General Properties tab, review the list of host aliases, and ensure that for each hostname a customer uses, ":[portNumber]" is appended, where portNumber is the SSL port. For example, if one host alias is "www.myCom.com", change it to "www.myCom.com:9443", if 9443 is your SSL port. Remove or replace the entry "www.myCom.com" if you do not want to allow non-SSL access to the site.
  • If you have added ":[portNumber]" to the host aliases, does the port number you specified match the SSL port specified for the application server(s)serving your resources? For each application server which you intend to serve SSL-encrypted resources, do the following:
    • Select the Services tab of the application server's properties in the administrative console.
    • Select the Web container service entry from the services list, then click Edit Properties.
    • Select the Transport tab. The host alias port should match the transport port property here.
  • Do the application servers have SSL enabled, and have the certificates and keyring files to support it been created? For each application server which you intend to serve SSL-encrypted resources, do the following:
    • Select the Services tab of the application server's properties in the administrative console.
    • Select the Web container service entry from the services list, then click Edit Properties.
    • Select the Transport tab.
    • For each entry in the HTTP transport list, select it and click Edit....
    • Verify that Enable SSL is selected
    • If Use global SSL default configuration is selected go to the Console > Security Center in the administrative console and click Default SSL Configuration.
    • Validate the key file name and password. You might need to consult with the person who created the file, or person who works with the third-party certificate provider, to get this information. If this file has not been created, review the documentation in the WebSphere Application Server InfoCenter on how to use the IKeyman utility (provided with WebSphere) to create SSL certificates and key files.
  • Since enabling SSL, have you propagated the configuration to the Web server (and its WebSphere Application Server plug-in)?
If SLL setup is correct, collect the following:

Cloned application server is never reached

If, based on log file output, Resource Analyzer output, or lack of any performance improvements, one or more clones are not getting reached (that is, are not participating in workload management), check these items:
  • If the immediate client of the cloned resource(s) is a Java standalone application, have you defined the CORBA and workload management bootstrap hosts?
  • Is workload management enabled for all servers in the domain? "Enabled" is the default, but this is worth reviewing if there is any possibility workload management has been disabled.
  • Are the cloned application servers started?
  • Have the cloned enterprise beans successfully started?
  • If the problem involves an entity bean, do you have Option C caching enabled in the EJB container?

Cannot start the cloned application server, or load or start the cloned servlet or enterprise bean

  • If you obtain errors in the administrative console starting an application server clone, an enterprise bean in a cloned server, or when a servlet is loaded or accessed for the first time, here are some items to to check:
  • If the application server is cloned horizontally (for example, on a machine different from that of the server group on which it is based) ask these questions:
    • Have all of the supporting directories and files been created on the clone-hosting servers, including EAR files and JAR files?
    • Have directory-dependent properties been updated on each cloned application server to correctly reflect its environment? See the topic, Creating clones on machines with different WebSphere installation directories or operating systems. Conversely, have any of these properties (like, classpath entries added to a Web module) been changed on the server group, causing incorrect, server-specific values to be rippled to clones?
  • Are you having problems loading, starting or calling an enterprise bean originally created to run under earlier versions of WebSphere Application Server? If so, was the enterprise bean JAR file created using the wlmjar utility? If this happened, remove it and replace it with the original, wmljar version of the enterprise JAR file. For details, see Migrating workload-managed enterprise beans from WebSphere Application Server Version 3.5 to WebSphere Application Server, Advanced Edition 4.0.x.
  • If the problem involves an entity bean, do you have Option C caching enabled in the EJB container?




Classpath and dynamic classloading


If WebSphere throws a Class not found or No class definition error or exception, and the referenced class is physically present, it is likely that the problem is happening for one of the following reasons:
  • The class has not been placed on the administrative server, application server, or web application classpath
  • The classpath on which the class has been placed is too low on the classpath hierarchy to be visible to the class that needs it (for example, it is referenced by a servlet, but it is on the classpath of a different web application in the same application server, rather than at the application server level).
  • The JAR file name or directory as defined on the classpath is misspelled, or the directory of the class does not start at the package root
If WebSphere Application Server loads a version of a class file different from the one physically present, it is likely that the problem is happening for one of the following reasons:
  • The process loading the class (such as, the administrative server or an application server) has not been restarted or has not yet reloaded the class
  • A different version of the same class is on a classpath, higher in the classpath hierarchy than the desired class file. For example, the administrative server is loading a JAR file from directory A, so when a Web application starts that has the same file name in directory B's classpath, its reference to the JAR file is ignored since its classes are already loaded
For a description of all of WebSphere Application Servers classpaths, the classpath hierarchy, and when classes get reloaded, see the InfoCenter article 6.4.1: Setting classpaths.

If you have reviewed your classpath settings, and the name and location of your class file and the JAR file (if any) which contains it, gather the following:

  • <websphere install dir>/bin/admin.config file
  • <websphere install dir>/config/server-cfg.xml file
  • standard output and error files from application server containing the problem resource
  • Output of the XMLConfig command (full export option)
  • EAR file or contents of directory which contains the problem enterprise application
  • Listing of the WebSphere Application Server directory structure (and any other directories containing not-loaded classes)
    • In Windows NT/2000 run "dir/s > dirlist.txt" from a root directory
    • On UNIX, run "ls -R > dirlist.txt" from a root directory
and obtain help from IBM.


User profile


If problems arise when implementing user profiles, here are some things to check:
Verify that you have set up all of the steps described in the InfoCenter article Configuring user profile support.
Have you:
  • Placed the access bean com.ibm.servlet.personalization.userprofile.UserProfile, or its JAR file, userprofile.jar, on a classpath so that it is visible to any servlet(s) or JSP file(s) calling user profile APIs?
  • Created an enterprise application in which you have included EJB modules with the user profile enterprise beans UP_ReadOnly and UP_ReadWrite, in userprofile.jar?
  • Deployed and installed the enterprise application?
  • Created a installation_root/properties/userprofile.xml containing configurable properties for managing user profiles?
  • Specified a valid data source in userprofile.xml file and verified its user ID and password?
  • If security is enabled, have you created roles for the user profile beans, and assigned to them the user IDs or groups of those who will be accessing the client servlets and JSP files?
If all of these steps appear to have been completed properly, and you are still having run-time problems with storing or retrieving user profile data,

Virtual hosting

If you have problems accessing resources served by one of the virtual hosts defined on your WebSphere Application Server domain, here are some things to check:

  • Is the address you are using correctly defined to your Web server? Can you access the welcome page of your Web server using the host part of the URI ("http://<host-name-or-ip-address>"), where the host name you enter represents the virtual host you are having problems with?
  • If not, do you have multiple virtual hosts (sometimes called virtual servers) served by the same physical Web server? If so, is your Web server configured correctly? Check the documentation for your Web server product. These are links for multiple virtual host configuration for some vendors:
  • If your virtual hosts appear to be correctly configured for your Web server, are they correctly configured in WebSphere Application Server? View the properties of your virtual host(s) in the administrative console.
    • Does the virtual host (for example, default host) contain a host alias which matches the host name used to access your Web browser? View the list of host aliases and add new entries as needed.
    • Does it include an entry for all forms of the host name which can be used to access the server (short name, fully qualified domain name, IP address)?
    • If the port your Web server is listening on is other than 80, or if you have URLs not on port 80, are these reflected in your host aliases (for example, do you have aliases of the form, "someHostName:nnnn", where "nnnn" is the port number)?
    • If you have SSL enabled on your Web server, do you have host aliases of the form, "<host name>:443" (assuming you are using the default SSL port of 443)?
  • Is your Web server running remotely (on a different server than WebSphere Application Server)? If so, have you copied the plugin-cfg.xml file to the Web server machine since updating virtual host information?
Use the Log Analyzer to look for errors related to the virtual host

If the problem is still unclear, look at these files for clues:

  • tracefile
  • native.log file of the application server which contains the resources not getting served
  • standard output and error files of the application server which contains the resources not getting served
  • >error and access logs of your Web server

    If you are still unable to resolve the problem, gather these files, plus

    and obtain help from IBM.



    Connection pooling

    If you encounter problems deploying application code that uses connection pooling, or encounter errors or exceptions when a Web application attempts to create or use a connection, here are some things to look at:

    • Has the application code been ported from a WebSphere Application Server 2.x or 3.0x server? If so, have deprecated or unsupported APIs been converted to the currently supported JDBC 2 APIs? If you are not sure, refer to the InfoCenter article Migrating to supported database connection APIs (and JDBC).
    • Is the connection to a DB2 database? If so, has WebSphere Application Server's environment been set up to use the DB2 JDBC 2 driver? This might not have been done, especially if WebSphere Application Server's repository is not DB2. See "Tips for data access programming" in the InfoCenter article, Obtaining and using database connections.
    • Browse the InfoCenter article, Tips for using connection pooling for best and worst practices regarding connection pool development and administration.
    • If exceptions are being thrown when an application attempts to obtain or use a connection, browse the InfoCenter article Handling data access exceptions.
    • Run the Log Analyzer to look for WebSphere-generated warnings and errors related to data access. Also look for errors in the standard output and error files of the application server which hosts the relevant Web or EJB module. If the warning or error messages are not clear, look for more detailed descriptions in the Messages section.
    • Use the jdbctest tool to access the problem data source outside of WebSphere Application Server, using the same ID and password you associated with the data source. If you cannot access the database with jdbctest, it's likely that WebSphere Application Server cannot either.
    • Contact your database administrator for help in determining whether the target database manager is running, there are available connections, and to monitor access from the database side to see if client requests are arriving.

    If you are still not able to diagnose the problem, gather


    and obtain help from IBM.



    Enterprise beans, EJB modules, and EJB containers


    If you have problems deploying an EJB module, loading an EJB module into an application server, or accessing enterprise bean methods from a client Java application, servlet, or other enterprise bean, here are some things to look at:

    • In the AAT, open the EJB module and use the "verify archive" menu option to validate directory paths
    • Browse the deployment descriptors of the EJB module for correctness in the AAT. Open the enterprise bean JAR file in the AAT and review its properties.
    • If you do not have access to the AAT, use the command jar -xvf to extract the files ejb-jar.xml and ibm-ejb-jar-bind.xmi from the EJB module's JAR file. Browse the files in a text or XML editor to verify classpaths, path and file and binding names. Verify the name(s) clients are using to access the bean match either the original JNDI bean name or one of the bind names.
    • If the enterprise bean was originally created for a previous release of WebSphere Application Server, review the article Migrating to supported enterprise bean specification.
    • Ensure that the enterprise bean name is in a package (for example, "com.mycom.MyBean" instead of "MyBean").
    • If the enterprise bean is an entity bean, use the jdbctest tool to access the database, using the same password and ID specified in the data source which the bean is associated
    • Use the Log Analyzer to look for related warning and error messages
    • Review the standard out and standard error files of the application server in which the enterprise bean is deployed
    • Check the deployment descriptors of the EJB module and any Web modules in which they have clients (like servlets) to ensure that the EJB references match (for example, that bindings are correct)

    If you are still unable to diagnose the problem, gather

    and obtain help from IBM.

    Several EJBs using local JNDI lookups for J2C connection factories are configured to go to a different connetion factory, but they are all going to the same connection factory

    One reason why you are having this problem is that the res-ref bindings might not be not set properly. Check ibm-application-bnd.xmi in %WAS_HOME%\installedApps\[ApplicationName]\META-INF\.

    Another possibility is that the enterprise bean references are bound to the same instance of their home class. This can happen when the enterprise beans have the same package and class name. The result is that only one instance of the home is created on the server, and only one res-ref mapping takes effect. This can be checked through the dumpnamespace tool, for example:

    2   (top)/CICSAdapterLog
    com.cna.im.CICS.Adapters._CICSAdapterLogHome_Stub  
        5   (top)/CICSTapAdapter
    com.cna.im.CICS.Adapters._CICSTapAdapterHome_Stub      
    113 (top)/CH3.CICSAdapterLog
    com.cna.im.CICS.Adapters._CICSAdapterLogHome_Stub      

    All three bean references are bound to com.cna.im.CICS.Adapters._CICSAdapterLogHome_Stub.


    Administrative client problems

    If you are having problems starting a client of the administrative server, like the administrative console, WSCP, or xmlconfig, here are some things to check:

    • If the problem process is the administrative console, see the topic Cannot start the administrative console.
    • Make sure WebSphere Application Server's administrative server is started and running
    • If you are running the client process remotely (not on the same machine as the WebSphere administrative server):
      • Are you specifying the host name and port (usually 900) of the WebSphere server when you invoke the client program?
      • Do you have TCP/IP connectivity between the machine you are running the client and the machine that is running WebSphere Application Server? Can you run the ping <hostname> command on the client machine, where <hostname> is the IP address or host name of the WebSphere Application Server serving machine? If not:
        • The WebSphere Application Server machine machine might be down
        • You might not have access from the client machine to the serving machine -- contact  your network administrator and ask
          • What is the serving machine's IP address or hostname on your network's name server?
          • If there is a firewall between the two boxes - if so, is the WebSphere Application Server bootstrap port (default 900) opened in the firewall?
    • WebSphere Application Server might not be listening for client requests on the on the port the client is sending on (usually 900).  Ask your WebSphere Application Server administrator if the bootstrap port you are using is correct.
    • Is the version of WebSphere Application Server the same as the version of the client program? Differences of version, revision and sometimes even fix pack level between the two can cause failure. Typically, this results in a low-level Java exception like ClassCastException or NullPointerException in the window from which the client was launched
    • Is WebSphere Application Server security enabled? If so,
      • Did a log-in prompt come up when the client was launched? If not, it could be that security was enabled since the client was installed, and the client does not know that the server is now secured. This can happen, for example, if the client is running remotely. Check the file <websphere install dir>/properties/sas.client.props on the client machine, if you are running the client from a remote machine. Ensure the following properties match the values in sas.server.props on the serving machine:
        • com.ibm.CORBA.securityEnabled
        • com.ibm.CORBA.loginUserid
        • com.ibm.CORBA.loginPassword
      • If a login challenge appeared, but the user ID and password was rejected, check the file <websphere install dir>/properties/sas.client.props on the client machine, if different from the server. Ensure the following properties match the values in sas.server.props on the serving machine:
        • com.ibm.CORBA.loginUserid
        • com.ibm.CORBA.loginPassword
    • If none of these tips help:
      • Look at the window from which the client was launched because there might be errors or exceptions that will explain the cause of the problem
      • Look at WebSphere Application Server <websphere install dir>/logs/tracefile file. If the client program contacted the WebSphere server and was rejected for some reason, there could be related errors.
      •  Run the Log Analyzer on the serving machine and look for warnings and errors

    If none of these steps help, gather any error messages and dialogs from the client, Log Analyzer, and tracefile file, and obtain help from IBM.

Go to previous article: Workload management for stand-alone Java clients Go to next article: Problem Determination versus Tuning

 

 
Go to previous article: Workload management for stand-alone Java clients Go to next article: Problem Determination versus Tuning