Troubleshooting and Tips | Pro Apache Tomcat 5/5.5 (Experts Voice in Java)

Finally, before I close this chapter, I’ll cover the typical problems that may occur when you install Tomcat. If you have further problems, you can find more material on the Tomcat Web site at http://jakarta.apache.org/tomcat/ and at http://java.sun.com as well as on various forums. You should also read the release notes available with each download.

The following are a number of problems typically encountered when first installing Tomcat.

The Tomcat Window Disappears

This is particularly difficult to diagnose and applies especially to Windows. Since the problem usually has one of two causes, however, you can start by diagnosing it and then move on to the known solutions.

If Tomcat doesn’t start, it can be run in the current shell or command prompt so you can see what the problem is. Type the following on Linux:

 # $CATALINA_HOME/bin/catalina.sh run

Or type the following on Windows:

 > %CATALINA_HOME%/bin/catalina run

This will produce the normal startup messages, and any errors will be displayed. These errors also appear in the log file in the CATALINA_HOME/logs directory. (You may have to set up logging for Tomcat 5.5.x; see Chapter 4.)

Check that you’re using the correct version of Java for the Tomcat version you’re trying to run. If you’re using JDK 1.4 with Tomcat 5.5, make sure the following files exist:

CATALINA_HOME\bin\jmx.jar
CATALINA_HOME\common\endorsed\xercesImpl.jar
CATALINA_HOME\common\endorsed\xml-apis.jar

If not, download the compatibility files from the Jakarta Web site.

The Port Number Is in Use

Tomcat uses port 8080 by default, as mentioned previously. You can check if another program is using this port by using netstat. Typing netstat (netstat -ln on Linux) into your shell/command prompt will list open ports on your system and should show the process that’s interfering with Tomcat. You have two options: shut the process down or change Tomcat’s port as described earlier.

A common problem is trying to start a new Tomcat instance when one is still running. This is especially true if it’s running as a daemon thread. If you suspect this is the case, you can check it by using telnet to connect to the socket, as follows, and see if you’re given a connection:

 $ telnet localhost 8080

If you’re awarded a connection, the screen goes blank rather than giving an error.

When you’re connected, type GET / and press Return or Enter. (Echo is turned off by default on Windows, so it looks a little strange because typing doesn’t appear to achieve anything.) On Windows, this results in the following output:

 HTTP/1.0 302 Found  Content-Type: text/html  Location: http://127.0.0.1:8080/  /index.jsp  Content-Length: 167  Servlet-Engine: Tomcat Web Server/3.2.1 (JSP 1.1; Servlet 2.2; Java 1.3.0; Windows  2000 5.0 x86; java.vendor=Sun Microsystems Inc.)  <head><title>Document moved</title></head>  <body><h1>Document moved</h1>  This document has moved <a href="http://127.0.0.1:8080/  /index.jsp">here</a>.<p>  </body>  Connection to host lost.  >

In this case, you have an instance of Tomcat 3.2.1 running in the background that’s stopping the new Tomcat instance from booting.

Even if you’re refused a connection, this indicates that a process is sitting on that port. If the connection fails, then try one of the other possibilities.