Skip to content
Tutorials Center
My learning

Topics

Lesson 31 of 37 ยท Troubleshooting

Reading Tomcat Logs and Stack Traces

Learn which Tomcat log files exist, what each records, how to read a Java stack trace and its Caused by chain, and how to adjust log levels with logging.properties.

When something goes wrong in Tomcat, the answer is almost always already written in a log file. The skill is knowing which file to open and how to read what is in it. Tomcat writes several logs for different purposes, and a Java stack trace, intimidating at first, follows strict rules that point you to the cause quickly.

This lesson tours the log files, shows how to change what gets logged, and teaches stack-trace reading with runnable stand-ins that create real exceptions and parse real traces. The Tomcat configuration is read-only.

The log files

By default everything goes into $CATALINA_BASE/logs:

File What it contains
catalina.YYYY-MM-DD.log Tomcat's own messages: startup, deployment, connectors, shutdown, warnings.
localhost.YYYY-MM-DD.log Messages from the web applications on the localhost host: uncaught exceptions in servlets and filters, listener failures.
localhost_access_log.YYYY-MM-DD.txt One line per request (see access logs).
manager.*.log, host-manager.*.log The management applications.
catalina.out Created by catalina.sh: everything written to standard output and error, including System.out.println and JVM crash messages.

On systems where Tomcat runs under systemd, the same output also appears in journalctl -u tomcat. In containers, log to standard output and let the platform collect it.

When an app fails to deploy, check catalina.log for the overall failure and localhost.log for the exception that caused it. A beginner mistake is reading only catalina.out's tail and missing the first error, which is usually the root cause. Search for the first SEVERE entry after the start of the problem, not the last one, since later errors are often consequences.

Log levels and format

Tomcat uses java.util.logging (JULI, its own implementation) configured by conf/logging.properties. Levels from quietest to chattiest are SEVERE, WARNING, INFO, CONFIG, FINE, FINER, FINEST.

PROPERTIES
# conf/logging.properties (excerpt)
handlers = 1catalina.org.apache.juli.AsyncFileHandler, 2localhost.org.apache.juli.AsyncFileHandler, java.util.logging.ConsoleHandler
.handlers = 1catalina.org.apache.juli.AsyncFileHandler, java.util.logging.ConsoleHandler

1catalina.org.apache.juli.AsyncFileHandler.level = FINE
1catalina.org.apache.juli.AsyncFileHandler.directory = ${catalina.base}/logs
1catalina.org.apache.juli.AsyncFileHandler.prefix = catalina.
1catalina.org.apache.juli.AsyncFileHandler.maxDays = 14

# turn on more detail for one subsystem only
org.apache.catalina.session.level = FINE
org.apache.coyote.http11.level = FINE

Raise the level only for the package you are investigating, then lower it again; FINE on everything floods the disk. Typical packages: org.apache.catalina.startup (startup), org.apache.catalina.core (contexts), org.apache.tomcat.util.net (connectors), org.apache.catalina.authenticator (login problems). Applications that use Log4j2 or Logback can route their logs to their own files; put their config inside the WAR and keep them out of Tomcat's files.

A log line: 14-Mar-2026 10:15:32.123 SEVERE [main] org.apache.catalina.core.StandardContext.startInternal One or more listeners failed to start. Full details will be found in the appropriate container log file. It has the time, level, thread, the class that logged it and the message. The [main] thread tells you whether it was startup (main) or a request (http-nio-8080-exec-7).

How a stack trace is organized

TEXT
java.lang.IllegalStateException: Cannot place order
    at com.example.shop.OrderService.place(OrderService.java:42)
    at com.example.shop.CartServlet.doPost(CartServlet.java:31)
    at jakarta.servlet.http.HttpServlet.service(HttpServlet.java:...)
    ...
Caused by: java.sql.SQLException: Connection refused
    at org.postgresql...
    ... 24 more

Read it like this:

  1. The first line is the exception type and message of the outermost exception.
  2. Each at line is a stack frame: the method that was running, newest first. Find the first frame in your package: that is where your code was when it failed.
  3. A Caused by: line starts the underlying exception. The last Caused by in the chain is the root cause, the one to fix. Here the root cause is the database being unreachable, not the IllegalStateException.
  4. ... 24 more means frames shared with the enclosing trace were omitted.

Framework frames (org.apache.catalina, jakarta.servlet) are usually noise. Look for your package names and for the Caused by.

Stand-in: walking the cause chain

This program builds a three-level exception chain and prints the root cause and the first frame in your own package, the two things you look for when reading a trace.

Java Stand-in: find the root cause

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 loop mirrors what a human does: follow getCause() to the end. The printed method is queryDatabase, the deepest method of ours on the stack, while the exception a user would see in the browser is the outermost RuntimeException.

Stand-in: triaging a log file

Real logs are long. A script that counts levels and extracts the first severe entry saves time. This stand-in works on a small sample in Tomcat's format:

Java Stand-in: log triage

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.

Note that Tomcat started ("Server startup in 3811 ms") even though the /shop context failed: Tomcat keeps running when one application fails. The server being up does not mean your application is. Look for the context's own status.

Habits that speed up diagnosis

  • Reproduce the problem and read only the log lines written during it (tail -f, or timestamps).
  • Note the thread name, which links a request line in the access log to its exception.
  • Search for Caused by and read the last one first.
  • Keep log files out of version control and never paste them publicly: they can contain tokens and personal data.
  • Raise log levels temporarily and turn them back, so the disk does not fill.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which log usually shows exceptions thrown inside your web application's servlets?

    Uncaught exceptions from the web applications on the localhost host are written to the localhost log.
  2. 2. In a stack trace with several Caused by sections, which one is the root cause?

    Each Caused by is the underlying exception; the last one is the original failure.
  3. 3. How do you get more detail from one Tomcat subsystem?

    JULI levels are set per package in conf/logging.properties.
  4. 4. Tomcat reports startup finished, but a context failed. What does this mean?

    One failed context does not stop the server, so check each application's startup messages.

Summary

  • catalina.log covers the server, localhost.log the applications, access logs the requests, catalina.out the console output.
  • Read the first error, follow Caused by to the last, then find your first frame.
  • Set log levels per package in logging.properties and revert afterwards.
  • A started server does not prove a healthy application.

Next: Startup and deployment errors