Skip to content
Tutorials Center
My learning

Topics

Lesson 32 of 37 ยท Troubleshooting

Common Tomcat Startup and Deployment Errors

Diagnose the most common Tomcat problems: address already in use, wrong JAVA_HOME, ClassNotFoundException, jakarta vs javax, failed contexts, 404 after deploy and 403 on the manager.

Most Tomcat problems on a new machine fall into a short list. The server will not start, a port is taken, a web application fails to deploy, or it deploys but returns 404. Each has a recognizable message and a short fix. This lesson goes through them in the order you are likely to meet them, shows how to confirm the cause, and demonstrates two of the underlying Java errors with runnable code. The Tomcat commands themselves are read-only because Tomcat cannot run on this site.

Start with the habit from reading Catalina logs: find the first SEVERE message, then follow the Caused by chain to the root.

Tomcat does not start at all

JAVA_HOME or the wrong Java version

Symptoms: The JAVA_HOME environment variable is not defined correctly, or UnsupportedClassVersionError: ... has been compiled by a more recent version of the Java Runtime. Each Tomcat release needs a minimum Java version (Tomcat 10.1 needs Java 11, Tomcat 11 needs Java 17). Fix by pointing the right JDK or JRE at it in bin/setenv.sh:

Terminal
export JAVA_HOME=/usr/lib/jvm/java-21-openjdk
export CATALINA_HOME=/opt/tomcat
"$CATALINA_HOME/bin/version.sh"      # prints Server version and JVM version

version.sh is the quick check: it shows which Tomcat and which Java are actually in use.

Address already in use

TEXT
SEVERE [main] org.apache.catalina.core.StandardService.initInternal Failed to initialize connector
 Caused by: java.net.BindException: Address already in use: bind

Another process owns port 8080 (or the shutdown port 8005). Find it with ss -ltnp | grep 8080 or lsof -i :8080 on Linux and netstat -ano | findstr :8080 on Windows, then either stop that process or change the port in the Connector. A frequent cause is a second Tomcat instance, or an old one that was never stopped. The demonstration below produces the same BindException in plain Java.

Java Stand-in: why a port is already in use

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

The first listener holds the port; the second asks for the same one and gets a BindException. Tomcat's connector failing to start is exactly this.

Permission denied on low ports

Binding to 80 or 443 as a normal user fails on Linux. Use 8080/8443 and a redirect, or grant the capability setcap cap_net_bind_service=+ep to Java. Do not run as root (see hardening).

The server starts but the app fails

ClassNotFoundException and NoClassDefFoundError

ClassNotFoundException means a class was requested by name and is not on the classpath. NoClassDefFoundError means it was present at compile time but is missing (or failed to initialize) at runtime. Causes:

  • A library missing from WEB-INF/lib (a dependency with provided scope that the server does not provide).
  • The same library in both WEB-INF/lib and Tomcat's lib, loaded by different classloaders so classes do not match (ClassCastException: X cannot be cast to X).
  • Servlet API jars inside the WAR: never package jakarta.servlet-api or javax.servlet-api in WEB-INF/lib; mark it provided.

This stand-in makes both errors visible:

Java Stand-in: the two missing-class errors

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

The second case teaches an important habit: a NoClassDefFoundError complaining about a class that clearly exists usually means its static initializer failed earlier. Look back in the log for the first ExceptionInInitializerError.

javax versus jakarta

Tomcat 10 and later implement Jakarta EE, where packages were renamed from javax.servlet to jakarta.servlet. A WAR compiled against javax.* fails on Tomcat 10+ with ClassNotFoundException: javax.servlet.http.HttpServlet or the app silently does nothing. Fix by migrating the code (and dependencies, e.g. a new Spring or Hibernate version), or use the migration tool at $CATALINA_HOME/bin/migrate.sh old.war new.war, or deploy it into the webapps-javaee directory so Tomcat converts it at deployment. Matching the Tomcat version to the framework's Jakarta level is the most common upgrade chore.

Context fails to start

The log says Context [/shop] startup failed due to previous errors and the app returns 404. Typical roots:

  • A listener or servlet with load-on-startup throws in init().
  • A broken web.xml (malformed XML, wrong schema version, a class name that does not exist).
  • A JNDI data source declared in context.xml that cannot connect or lacks its driver jar in Tomcat's lib.
  • Spring or Hibernate failing to build its context: read the bottom Caused by for the missing bean property, bad URL or missing table.

It deploys but returns 404

  • Wrong context path: the WAR name is the path. shop.war is served at /shop; ROOT.war at /. A name with a version (shop-1.2.war) gives /shop-1.2; use # in the file name for nested paths (api#v2.war becomes /api/v2) or set <Context path> in a context file.
  • Hit /shop and expect an index file: check welcome-file-list and where the file is (not hidden under WEB-INF, which is never served).
  • The servlet mapping is wrong: the URL pattern in @WebServlet or web.xml does not match what you call.
  • metadata-complete="true" in web.xml turns off annotation scanning, so @WebServlet classes are ignored.
  • Auto-deploy is off and the WAR was added while running: use the manager, or restart (see hardening for the autoDeploy trade-off).

The manager returns 403

Since Tomcat 8.5 the manager is restricted to localhost by webapps/manager/META-INF/context.xml, and a user needs a role in tomcat-users.xml. A 403 usually means the RemoteCIDRValve blocks your address (valves) or the user has no manager-gui role. Change the allowed address deliberately; do not delete the valve.

A diagnostic order that works

  1. version.sh and java -version: correct Java?
  2. Port free? (ss/netstat)
  3. First SEVERE in catalina.log, then localhost.log.
  4. ls webapps and work/Catalina/localhost: was the WAR unpacked? Is there a stale directory from an older version? Delete the unpacked folder and work contents if the WAR changed but the old copy persists.
  5. Deploy the simplest possible WAR to prove the server itself is fine.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Tomcat logs java.net.BindException: Address already in use. What is the most likely cause?

    A BindException on start means the port is taken, often by another Tomcat instance.
  2. 2. A WAR built for javax.servlet fails on Tomcat 10 or 11. Why?

    Jakarta EE renamed the packages; code and libraries must use jakarta.* or be converted.
  3. 3. A NoClassDefFoundError for a class that exists in the WAR most often indicates what?

    After a failed static init the class is unusable, and later uses throw NoClassDefFoundError.
  4. 4. Where is shop.war served by default?

    The WAR file name minus the extension becomes the context path; only ROOT.war is served at /.

Summary

  • Check the Java version and port first, then the first SEVERE message.
  • ClassNotFoundException and NoClassDefFoundError point to classpath problems or failed static initializers; do not bundle the Servlet API.
  • Tomcat 10+ needs jakarta.*; convert or upgrade the application.
  • A started server can host failed contexts; 404 usually means the context did not start or the path is wrong.

Next: Memory leaks and thread dumps