Alexis Kestler
As an avid Java developer and Tomcat enthusiast, I know how frustrating it can be when your Tomcat server gets stuck trying to start up. A non-starting Tomcat can completely halt development and deployment work.
In this comprehensive guide, I‘ll share my insider knowledge to help diagnose why your Tomcat instance is getting stuck and provide proven solutions to get it back up and running.
Peering Under the Hood – How Tomcat Starts Up
Before we fix the problem, we should understand what‘s happening under the hood during a normal Tomcat startup.
When you first initiate startup, Tomcat begins by:
- Processing startup commands
- Initializing protocol handlers like HTTP/AJP connectors
- Loading server configurations from server.xml
- Deploying web applications
- Starting lifecycle listeners
- Initializing naming resources like JNDI
- Starting up deployed webapps
Once all this is done, you‘ll see the log message:
INFO: Server startup in XXXX msThis indicates a successful startup. If you don‘t see this, it means something is preventing one of the startup steps from completing.
Top 10 Reasons for Tomcat Startup Failure
Through troubleshooting myriad stuck Tomcats over the years, I‘ve narrowed down the most common culprits behind startup failures:
1. Port conflicts – This is one of the top reasons. Another process occupies Tomcat‘s default ports like 8080 or 8009 before it starts.
2. Insufficient memory – The JVM runs out of heap space to load classes and webapps. Also causes OutOfMemoryErrors.
3. Corrupted Tomcat installation – Bad downloads or incomplete updates can corrode Tomcat‘s internal libraries.
4. Too many webapps/JARs – Trying to start too many large webapps and JARs overloads the startup sequence.
5. Java version incompatibility – Unsupported Java versions or bugs in newer JDKs can wreak havoc.
6. Native library missing – If Tomcat can‘t find its native Apache Portable Runtime (APR) libraries, startup stalls.
7. File permission issues – Tomcat needs read/write access to directories like temp, work, logs etc.
8. Connector configuration – Wrong settings for connectors in server.xml like protocol, address, threads can stall startup.
9. Entropy problems – SecureRandom number generation failures hang the warmup phase.
10. Custom JAR conflicts – Badly coded or incompatible customer JARs and listeners can stop startup.
Now let‘s see how to diagnose and fix each of these common issues.
Handling Port Conflicts
One of the first things to check is whether another process is already using the ports Tomcat needs, like 8080 and 8009.
Use a command like netstat -anop | grep 8080 to confirm if the ports are occupied. If they are, you‘ll need to either stop the other process, or configure Tomcat to use different ports in server.xml.
Changing the default ports to something else like 9090 for HTTP and 9009 for AJP often resolves conflicts.
Dealing with Insufficient Memory
The Java Virtual Machine needs enough heap memory to load all the classes and libraries required by Tomcat and your webapps.
If you have large applications, the default heap size of 128MB can quickly run out. This manifests as java.lang.OutOfMemoryError during startup.
Solving this requires allocating more memory for Tomcat using the -Xmx and -Xms JVM arguments in catalina.sh or setenv.sh.
As a rule of thumb, you may need 512MB to 1GB heap for a medium sized production instance. Set -Xmx and -Xms to 1024m or higher as needed.
Recovering from a Corrupted Installation
Sometimes a bad download or incomplete upgrade can leave your Tomcat install corrupted with missing libraries and dependencies.
This can lead to nasty NoClassDefFoundErrors or other errors during startup.
Unfortunately, the only solution is to download a fresh copy of Tomcat from tomcat.apache.org and reinstall it from scratch after deleting the corrupted version.
Be sure to backup your conf, logs, webapps and data before replacing it with the new Tomcat instance.
Reducing Webapp and JAR Overload
The more webapps and JARs you have, the more startup time and memory it takes.
If you have several very large webapps (50MB+), the startup sequence may exceed capacity and hang.
Try removing some non-essential webapps and JARs from webapps and lib directories and see if startup improves.
Also consider Lazy loading some webapps that are not needed at bootstrap by removing or renaming their WAR files until after startup.
Checking Java Version Compatibility
While newer Java versions add features and performance, they can also introduce bugs that break Tomcat integration.
Double check you are using a JDK version that your Tomcat release officially supports. For reference, Tomcat 9.x requires JDK 8.x and Tomcat 10.x needs JDK 11.x.
Also try updating Java or switching JDK versions to see if it stabilizes Tomcat. For example, AdoptOpenJDK offers lightweight and compatible options.
Loading the APR Native Library
For peak performance, Tomcat utilizes APR native libraries for handling HTTP connections and SSL.
If Tomcat complains at startup that these native libraries are missing, download and install the "tomcat-native" library package for your OS from tomcat.apache.org.
Also ensure java.library.path in catalina.sh is set correctly to the folder containing the APR binaries.
Checking File Access Permissions
Tomcat requires read/write access to folders like temp, work, logs and webapps to operate properly.
Sometimes strict permissions can prevent the Tomcat user from accessing these paths, leading to cryptic errors.
Test by temporarily adding write permissions to the conf, logs, temp and webapps folders, and see if it makes a difference. Don‘t leave it open in production though.
Reviewing Connector Configuration
The Connector elements defined in server.xml control how Tomcat listens for network requests over protocols like HTTP/HTTPS.
An incorrect protocol, address, or missing attributes like connectionTimeout can all prevent successful connector startup.
Check your connector settings against the default configuration that ships with Tomcat for debugging.
Seeding Random Number Generation
During startup, Tomcat needs to generate secure random numbers for encryption purposes.
This relies on having a good entropy source, which is sometimes missing on virtual machines and docker hosts.
The lack of randomness can indefinitely hang Tomcat‘s initialization routines.
Fix this by adding the "-Djava.security.egd=file:/dev/urandom" option to JAVA_OPTS in catalina.sh, to seed the SecureRandom algorithm.
Isolating Problematic Listeners and JARs
If you have custom listeners, validators or JARs in Tomcat‘s lib folder, any issues with those bits of code can halt the startup sequence.
Temporarily remove or rename all the additional classes and 3rd party JARs you added, so Tomcat boots with just the default libraries.
Then add them back one by one to identify which component is problematic. Exclude any buggy JARs from deployment.
Ready for Take Off!
With diligent troubleshooting following this guide, you should be able to get past most stuck Tomcat scenarios and have your instance starting reliably again.
Be sure to optimize monitoring, logging and gc settings as well for smooth sailing at run time. Let me know if any strange new startup issues crop up, and we‘ll get them debugged for liftoff!
