Sun Java System Application Server Platform Edition 8.2 Troubleshooting Guide

Chapter 2 Common Problems

This section covers the most common problems you may encounter when using the Application Server:

asadmin start-domain Command Fails

The command asadmin start-domain fails with one of the following errors:

Error: CLI143 There is more than one domain...

Description

When issued with no arguments, the command asadmin start-domain fails with the error:

CLI143 There is more than one domain in C:\\Sun\\AppServer\\domains.
Please use operand to specify the domain.
CLI156 Could not start the domain null.

This error occurs when there is more than one domain in the domains directory, none of them is named domain1, and no domain is specified with the start-domain command.

Solution

Specify the domain when issuing the start-domain command:

asadmin start-domain domain1

Error: Could Not Start Domain

Description

This message comes from Application Server 8. The full message looks like either:

Could not start the domain.
There are no domains.

or

Could not start the domain.
No default domain. Need to enter a domain.

This error occurs when Application Server 8 is installed on the same system, and its asadmin command (at /usr/sbin) is found on the PATH before the asadmin command for Application Server 8 at install_dir/bin. The situation is especially likely to occur on Solaris/Linux systems when . is not specified as part of the PATH variable. Without . in the PATH, the asadmin command in /usr/sbin is found first, even when the current directory is install_dir/bin.

Solution

Make sure install_dir/bin is in the PATH ahead of /usr/sbin, or that . is in the PATH ahead of /usr/sbin if you access asadmin by changing directories to install_dir/bin. Alternatively, if you do change to install_dir/bin to run asadmin, be sure to include./ in the command name; for example:


cd install_dir/bin
./asadmin

Automatically Restarting a Domain or Node Agent on Reboot

If your domain or node agent is stopped unexpectedly (for example, if you need to restart your machine), you can configure your system to automatically restart the domain or node agent on reboot.

Restarting Automatically on UNIX Platforms

Restarting a Domain

To restart your domain on a UNIX platform, add a line containing the appropriate asadmin start-domain command to your /etc/inittab file. If you use /etc/rc.local, or your system’s equivalent, place a the desired asadmin command in /etc/rc.local.

For example, to restart domain1 for an Troubleshooting Guide installed in the /opt/SUNWappserver directory, using a password file called password.txt, add the following line to /etc/inittab or /etc/rc.local:

das:3:respawn:/opt/SUNWappserver/bin/asadmin start-domain --user admin 
--passwordfile /opt/SUNWappserver/password.txt domain1

Be sure to put the text on one line. The first three letters are a unique designator for the process and can be altered.

Restarting a Node Agent

To restart a node agent, the syntax is similar. For example, to restart agent1 for an Troubleshooting Guide installed in the /opt/SUNWappserver directory using a password file called password.txt, add the following line to /etc/inittab or /etc/rc.local:

das:3:respawn:/opt/SUNWappserver/bin/asadmin start-node-agent --user admin 
--passwordfile /opt/SUNWappserver/password.txt agent1

Restarting Automatically on the Microsoft Windows Platform

To restart automatically on Microsoft Windows, create a Windows Service. Use the appservService.exe and appserverAgentService.exe executables shipped with Sun Java System Application Server in conjunction with the Service Control command (sc.exe) provided by Microsoft.

Starting and Stopping a Domain

To create a service called SunJavaSystemAppServer DOMAIN1 that starts and stops domain1 using password file C:\\Sun\\AppServer\\password.txt, run the following command:


C:\\windows\\system32\\sc.exe create domain1 binPath= "C:\\Sun\\AppServer\\
lib\\appservService.exe \\"C:\\Sun\\AppServer\\bin\\asadmin.bat start-domain
--user admin --passwordfile C:\\Sun\\AppServer\\password.txt domain1\\" 
\\"C:\\Sun\\AppServer\\bin\\asadmin.bat stop-domain domain1\\"" 
start=auto DisplayName= "SunJavaSystemAppServer DOMAIN1"

Starting and Stopping a Node Agent

To create a service that starts and stops the node agent agent1, run the following command:


C:\\windows\\system32\\sc.exe create agent1 binPath= "C:\\Sun\\AppServer\\
lib\\appservAgentService.exe \\"C:\\Sun\\AppServer\\bin\\asadmin.bat 
start-node-agent --user admin --passwordfile C:\\Sun\\AppServer\\
password.txt agent1\\" \\"C:\\Sun\\AppServer\\bin\\asadmin.bat 
stop-node-agent agent1\\"" start=auto DisplayName="SJESAS_SE8.1 AGENT1"

Note –

The start and stop commands entered as part of the binPath= parameter must have the correct syntax. To test, run the commands from the command prompt. If the commands do not properly start or stop the domain or node agent, the service will not work correctly.

Also, do not use a mixture of asadmin start and stop commands and service start and stops. Mixing the two can cause the server status to be out of sync. For example, the service might not show that the component has started even though the component is not running. To avoid this situation, always use the sc.exe command to start and stop the component when using services.


Security for Automatic Restarts

Handle the password and master password required when starting in one of the following ways:

Cannot Find Log Files

The following Application Server logs are useful for troubleshooting installation problems:

Accessing Local Server Fails (http://localhost:8080)

Things to check for this error include the following:

Did the Server Start?

Description

If the console window is still open, the expected message is:

Domain domain Started

where domain is the name of the default domain. This indicates that the default domain was started successfully.

If the console window is already closed, check for messages in the log file:

install_dir/domains/domain1/logs/server.log

If startup was successful, the expected message is similar to that on the console, and appears at the end of the log file:

[INFO][...][..][date&time][Application server startup complete .]

Was the Server Started at the Expected Port?

Description

The server might be running at a different port number than expected, either because it was intentionally installed there, or because another server was already running on the default port when the server was installed.

ProcedureTo determine which port number the server is actually using

Steps
  1. Examine the server's configuration file:


    install_dir/domains/domain1/config/domain.xml
  2. Find the http-listener element.

  3. Inspect the value of the port attribute.

    Be sure to enter the correct port number when invoking the server.


    Note –

    The server's default port number is 8080, however, there are a number of ways in which the expected value can change:

    • A different port number was specified during installation.

    • A previous installation exists.

    • If the specified port number is already taken by another application when the server is started, the port number rolls forward to the next available number. For example, if a server is already running on the default 8080 port, the new Application Server instance uses port number 8081. If two servers are running, the port number rolls to 8082, and so on.


Accessing Remote Server Fails

When attempting to open the start page of the Application Server, the initial screen does not appear.

Things to check include the following:

Is the Server Available Locally?

Description

If the server cannot be accessed from the web, but it is running locally, then the server is actually running.

Solution

Verify that the server is running locally.

ProcedureTo verify that the server is running locally

Steps
  1. Log on to the machine where the server is running.

  2. Go to the local web page. For example, if 8080 is the default port, go to:


    http://localhost:8080/

    If the start page does appear, there is a problem with the web connection that prevents accessing the server remotely. If the start page does not appear, see Did the Server Start?

Is the Proxy Setting Causing a Problem?

Description

The server should be accessible directly from the host on which it is running (localhost); for example, using the default port, 8080:

http://localhost:8080/

Solution

A server instance running on localhost may not be accessible if the server host machine is connected to the web through a proxy. To solve this problem, do one of the following:


Note –

To find the host name and domain for the localhost machine:


Cannot Access the Administration Console

The Administration Console provides an interface for administrative functions. If the Administration Console is not accessible, it might be for one of several reasons.

Is the Application Server Running?

Description

The server must be running before the Administration Console can be accessed.

Solution

Review the information in Did the Server Start? to determine if the server is running.

Is the Administration Console Running on the Expected Port?

Description

The default port number for the EE and SE Administration Console is 4849; for the PE Administration Console it is 4848. Also note that the URL for the EE and SE console requires secure HTTP (https://servername:4849.), whereas the PE console uses standard HTTP (http://servername:4848). However, it could be running on a different port number than expected, either because it was intentionally installed there, or because that port was taken when the server was started.

Solution

Refer to Was the Server Started at the Expected Port? for guidelines on verifying the port on which the Administration Console is running, and be sure to enter the correct port number and HTTP protocol when invoking the Administration Console.

Is the Security Manager Disabled?

Description

According to the J2EE 1.4 Specification, the Security Manager is not optional; it must be enabled in the Application Server. Since there is no configuration interface in the Application Server for disabling the Security Manager, it can only be disabled by directly modifying the domain.xml configuration file in such a way that the following line is removed:

<jvm-option\>-Djava.security.policy=yourPolicy</jvm-option\>

Solution

The -Djava.security.policy=yourPolicy option must be present in the domain.xml file to access the Administration Console.

Cannot Access a Server Application

If a particular application cannot be accessed through the Application Server, some things to check include the following:

Is the Application Server Running?

Description

If the Application Server is not running, applications will not be accessible.

Solution

Review the information in Did the Server Start? to determine if the server is running. The server must be running before a server application can be accessed.

Was Application Deployment Successful?

Description

An application must be successfully deployed before it can be accessed.

Solution

Check the server's log file:

install_dir/domains/domain1/server.log

Invalid User or Password When Using Don’t Prompt Option

You are getting the error, Invalid user or password, but you installed the system with the Don't Prompt option, so the password should be supplied automatically.

Description

The correct password may not have been specified during installation, or it may not be passed when the domain is started.

Solution

Check the password in the .asadminprefs file. On UNIX/Linux systems, it is in the home directory for the user under which the server was installed. On Windows, it is in C:\\Documents and Settings\\username. The contents look something like this:

AS_ADMIN_USER=admin
AS_ADMIN_PASSWORD=administrator

Administrator User Name or Password Not Known

If you have forgotten the administrator user name, you can find it by inspecting the .adminprefs file, as described in the section above, or by inspecting the install_dir/domains/domain1/config/keyfile, where domain1 is the default domain. For a different domain, substitute its name in the path.

If you have forgotten the administrator password, you will need to create a new user name-password pair by removing the user name and password, creating new ones, and restarting the server. (You will not be able to read the password, because it is encrypted in the keyfile.)

ProcedureTo remove the user name and password completely

Steps
  1. Stop the server, if it is currently running.

  2. Change to the appropriate WEB-INF directory; for example:


    install_dir/lib/install/applications/adminapp/adminapp_war/WEB-INF
  3. Comment out the entire <security-constraint\> element in the web.xml file.

    Do not delete the element, as you will be reenabling it later. This action disables security for command-line operations.


    Note –

    The commands will still expect a value for --username (or -u) and --password (or -w). But these can be dummy values, since the server side does not impose any security.


  4. Start the server.

    At this point, the server does not have command-line security.

  5. Run the following command:


    asadmin create-file-user --user <dummy\> --password <dummy\>
     --userpassword <new_secret\> --groups asadmin <new_user_id\>

    This command creates the following new entry:


    <install_dir\>/domains/domain1/config/keyfile
  6. Uncomment the <security-constraint\> element in web.xml file.

  7. Restart the server for the new user name-password to take effect.


    Note –

    When the server is started, any remote command-line operations will need new_user_id and new_secret as user name and password.


Server Will Not Start on Windows (Port Conflict)

If a message similar to the following is displayed when starting the Application Server on Microsoft Windows, a server port conflict has occurred:

Address already in use

This error occurs when another application is running on the Application Server port (default 8080), or because a previous instance of the Application Server did not shut down cleanly.

Other things to check include the following:

Is Another Application Running on the Server's Port?

If another application is using the server's port, stop the other application, then restart the Application Server.


Note –

The installer attempts to avoid port conflicts by choosing the next available port when the default port is in use—but that only works if application using the default port was running when the Application Server was installed.


Has an Ungraceful Shutdown Occurred on a Previously Running Server?

Use the asadmin stop-domain command to stop the server, or explicitly kill the Java process and then restart the Application Server.

Port Conflicts Debugging Multiple Instances on the Same Server

Description

Port conflict errors can occur when debugging multiple instances on the same server that are part of the same cluster.

Solution

Modify the domain.xml file to remove the address attribute from the -Xrunjdwp option in the java-config element for the cluster. This results in the JVM choosing a random debug port for the instance. The port number chosen for the instance is displayed in the server log when it is started; for example:

Two Server Instances Bind to Same Port on Windows

Description

This problem only occurs on Windows 2000/XP systems with the Application Server Enterprise Edition (not Platform Edition) software, and is due to a known Windows security flaw rather than a problem with the Application Server itself.

The problem occurs when two or more instances of the Application Server are created using the same port number for the instanceport option; for example:

asadmin create-domain -adminport 5001 <options\> -instanceport 6001
 <domain\
asadmin create-domain -adminport 5002 <options\> -instanceport 6001
 <domain\>

When the two domains are started on a UNIX/Linux system, a port conflict error is thrown and the second instance fails to start. However, when the two domains are started on Windows 2000/XP, no error is thrown, both server instances start, but only the first instance is accessible at the specified port. When that first server instance is subsequently shut down, the second instance then becomes accessible. Moreover, when both instance are running, the Windows netstat command shows the duplicate listeners as active, but only the first listener can respond to requests.

Solution

Be sure to use unique port numbers for all server instances on Windows systems.

Error: System cannot find the path specified

Description

This error message occurs when attempting to start the server after deleting the J2SE directory that was specified during installation. This situation generally occurs after being informed during the install that the J2SE platform needs an upgrade, and the upgrade takes place after the Application Server installation.

Solution 1

To use the new J2SE for all domains, change the AS_JAVA variable in asenv.conf (Solaris/Linux), or asenv.bat (Windows).

Solution 2

The J2SE version can be changed on a per-domain basis by modifying the java-home attribute for the java-config element in the domain’s domain.xml file.

<java-config ...
java-home="path"
...\>

Solution 3

A more time-intensive solution is to uninstall and then reinstall the server.

Application Generates Error persistence.support.JDODataStoreException

Description

A com.sun.jdo.api.persistence.support.JDODataStoreException is generated by an application, with a nested java.sql.SQLException indicating a duplicate primary key.

Even if the application is checking for a CreateException, it does not see one. The Enterprise JavaBeans specification requires a CreateException to be thrown only if two beans with the same primary key are created in the same transaction, so a CreateException is not thrown on transaction rollback if two entity beans with duplicate primary keys are created.

Solution

If an application creates an entity bean with a duplicate primary key, check to see if the primary key exists by calling findByPrimaryKey before calling create.

Using asadmin set Command May Produce Unexpected Results

Description

Unexpected results are returned when setting variables in a command, such as:

asadmin set name={$a-b}

In this case, name is set to b, not {$a-b} because the shell syntax ${a=b} is interpreted as “if the variable a is unset, substitute the value b, otherwise substitute the value of a.” This is standard shell behavior. For example, consider the following:

asadmin set default-config.http-service.http-listener.http-listener-1.port=
${http-listener-1-port}

In this case, default-config.http-service.http-listener.http-listener-1.port is set to listener-1-port, which is invalid.

Cannot Undeploy Or Redeploy Application With Open Streams to Jar Files (Windows Only)

Description

On Windows systems, after running an application, subsequent attempts to undeploy it or redeploy it throw exceptions about the server being unable to delete a file or rename a directory.

On Windows systems, an application may use getClass().getResource or getResourceAsStream methods to locate a resource inside the application, particularly in jar files that are in the application or accessible to it. If the streams remain open, subsequent attempts to redeploy or undeploy the application can fail. In addition, the Java runtime by default caches streams to jar files for performance reasons.

Solution

Be sure to close streams opened by your applications. Also, if an application needs to be redeployed or undeployed repeatedly, and also needs to obtain a resource from a jar file using getResource or getResourceAsStream, consider using getClass().getResource which returns a URL object, then invoke the url.setUseCaches method to turn off caching for that jar file, and then use url.getInputStream() to obtain the stream.

Although turning off caching for accesses to the jar file can slow down performance, this approach does allow the application to be undeployed or redeployed. Note also that if the getClass().getResourceAsStream method is used instead, then the jar file in which the resource is located will be cached (this is the default Java runtime setting) and remain open until the server is stopped.

Cannot Reinstall Application Server After Manual Deletion of Directories

Description

If the Application Server directories are deleted manually rather than by means of the included uninstall the program, subsequent attempts to reinstall the Application Server in the same directory fail. This is because the installation directory information stored in /tmp/productregistry file remains even though the program directories have been removed.

Solution 1

Remove Application Server directory information from the <location\> property entries in the /tmp/productregistry file; for example, change:

<location\>/opt/SUNWappserver/jdk</location\>

to

<location\></location\>

Solution 2

Reinstall the Application Server in a different directory.

Cannot Produce a JVM Thread Dump After Server Crash

Description

If the Application Server crashes, the server dumps a core file and, by default, restarts with the -Xrs flag, which prevents the dump of a JVM thread dump.

Solution

ProcedureTo enable a JVM thread dump

Steps
  1. Comment out the -Xrs flag in the server.xml file for the Application Server.

  2. Kill the server process (kill -3 on UNIX; Ctrl+Break on Windows).