Sun Java System Application Server 8.1 Platform Edition 2005Q1 Troubleshooting Guide |
Chapter 2
Common ProblemsThis section covers the most common problems you may encounter when using the Application Server:
asadmin start-domain Command FailsThe 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 RebootIf 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 Application Server 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 Application Server 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.
- The sc.exe command comes with Windows XP and is either located in the C:\windows\system32 directory or C:\winnt\system32 directory.
- As of this writing, the Windows 2000 sc.exe is available for download at: ftp://ftp.microsoft.com/reskit/win2000/sc.zip. For more information on using sc.exe, see:
Use appservService.exe and appservAgentService.exe as follows:
C:\winnt\system32\sc.exe create service_name binPath= \"fully_qualified_path_to_appservService.exe \"fully_qualified_path_to_asadmin.bat start_command\" \"fully_qualified_path_to_asadmin.bat stop_command\"" start= auto DisplayName= "display_name"
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"
Security for Automatic Restarts
Handle the password and master password required when starting in one of the following ways:
- On Microsoft Windows, configure the service to ask the user for the password.
- In the Services Control Panel, double-click the service you created.
- In the Properties window, click the Log On tab.
- Check “Allow service to interact with desktop” to prompt for the required passwords when starting the component.
You have to log in to see the prompts, and entries are not echoed back as you type them. This method is the most secure way to use the services option, but user interaction is required before the service becomes available.
If the “interact with desktop” option is not set, the service stays in a “start-pending” state and appears to hang. Kill the service process to recover from this state.
- On Windows or UNIX, create a domain using the --savemasterpassword=true option and create a password file to store the admin password. When starting the component, use the --passwordfile option to point to the file that contains the password. The admin password can also be added by using the --password option with the asadmin start command. Be aware that this method is less secure because the admin password is stored in clear text.
For example:
- Create a domain with a saved master password. Using this syntax, you are prompted for the admin password and master password:
asadmin create-domain --adminport 4848 --adminuser admin
--savemasterpassword=true --instanceport 8080 domain1- On Windows, create a service using a password file to populate the admin password:
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= "SJESAS_PE8.1 DOMAIN1"
- Creating a service using a password that is populated from a command line option:
C:\windows\system32\sc.exe create domain1 binPath= "C:\Sun\AppServer\lib\appservService.exe \"C:\Sun\AppServer\bin\asadmin.bat start-domain --user admin --password adminadmin domain1\" \"C:\Sun\AppServer\bin\asadmin.bat stop-domain domain1\"" start= auto DisplayName= "SJESAS_PE8.1 DOMAIN1"
Cannot Find Log FilesThe following Application Server logs are useful for troubleshooting installation problems:
Both the installation and uninstallation programs create log files and log all installation and uninstallation events to these files. The primary purpose of these log files is to provide troubleshooting information.
In addition to installation program messages and log files, operating system utilities such as pkginfo and showrev on Solaris and rpm on Linux can be used to gather system information.
Log file entries include information about the attempted action, the outcome of the action, and, if applicable, the cause of failure. The log files contain the following types of message entries:
- INFO – These messages mark normal completion of a particular installation tasks.
- WARNING – These messages mark non-critical failures. Warning messages generally contain information about the cause and the nature of the failure, and also provide possible remedies.
- ERROR – These messages mark critical failures that cause installation or uninstallation status to be reported as Failed. Error messages generally provide detailed information about the nature and the cause of the problem that occurred.
The application server logs are located in install_dir/domains/domain1/logs/.
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.
To determine which port number the server is actually using:
Be sure to enter the correct port number when invoking the server.
Accessing Remote Server FailsWhen 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
To verify that the server is running locally:
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:
Cannot Access the Administration ConsoleThe 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 ApplicationIf 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
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.
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 ServerDescription
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.
Example
Before
debug-options="-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=9009"
After
debug-options="-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=n"
Two Server Instances Bind to Same Port on WindowsDescription
This problem only occurs on Windows 2000/XP systems with the Application Server EE (not PE) 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”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.JDODataStoreExceptionDescription
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 ResultsDescription
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.
Example
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 DirectoriesDescription
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 CrashDescription
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