Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Add binary search to the Common Troubleshooting Scenario


  1. Look into Tomcat access log (the log file generated by AccessLogValve).
    1. If your request is not listed there, then it has not been processed by Tomcat. You need to look elsewhere (e.g. at your firewall).
    2. You will see what IP address your client is using, and whether it is using an IPv4 ( or IPv6 address (0:0:0:0:0:0:0:1).
      Modern operating systems can use IPv6 addresses for localhost / local network access, while external network is still using IPv4.
  2. Take a thread dump. This way you will find out what Tomcat is actually doing.
    1. If you are troubleshooting some process that takes noticeable time, take several (three) thread dumps with some interval between them. This way you will see if there are any changes, any progress.
  3. Try debugging.
    1. A good place for a breakpoint is org.apache.catalina.connector.CoyoteAdapter.service() method. That is the entry point from Tomcat connectors and into the Servlet engine. At that place your request has already been received and its processing starts.
  4. If you did a long-awaited upgrade, jumping over several years worth of Tomcat releases, and something broke, and you have no clue,
    1. Reading Migration guides may help.
    2. It may help to do a binary search (aka bisecting) to locate the version of Tomcat that triggered the change. If your issue is easy to reproduce, it may be pretty fast. Just 7-8 tries may cover a range of 100 versions. Once you know the version and its release date, the following resources are available:
      1. The release announcement.
        See "former announcements" link at the bottom of the front page of the Apache Tomcat site.
        An announcement mail message can also be found in the archives of the "announce@" mailing list.
      2. The changelog. A release announcement usually has a link to it.
      3. Archives of the "users@" mailing list. You may look for discussions that happened a month or two after the release.

Troubleshooting unexpected Response state problems