Tomcat SEVERE Error deploying web application: reading startup failures in catalina.out

The line you searched for looks something like this in catalina.out:

SEVERE [...] org.apache.catalina.startup.HostConfig.deployWAR Error deploying web application [...]
java.lang.IllegalStateException: ContainerBase.addChild: start: org.apache.catalina.LifecycleException: Failed to start component [StandardEngine[Catalina].StandardHost[localhost].StandardContext[/yourapp]]

That stack is a wrapper. The class that actually failed, the missing dependency, the listener that threw, or the NoSuchMethodError from a library clash is not in catalina.out. It is in localhost.YYYY-MM-DD.log in the same $CATALINA_BASE/logs directory. The Tomcat default logging.properties routes org.apache.catalina.core.ContainerBase.[Catalina].[localhost] to the 2localhost.org.apache.juli.AsyncFileHandler, which writes that file. The SEVERE line in catalina.out only tells you the deploy failed and that the context is now a FailedContext placeholder rather than a StandardContext.

The fix sequence is backwards from what most operators try first. Do not stare at catalina.out. Do not restart Tomcat yet. Confirm the context is FAILED via the Manager, open localhost.<date>.log, and read the full Caused by: chain.

What this means

When HostConfig.deployWAR() (or deployDirectory()) catches a LifecycleException from context start, it logs the SEVERE wrapper and substitutes a FailedContext for the application. The FailedContext keeps the path visible in the Manager so you can see it failed, but the application is not loaded. getStartTime() returns -1. Requests to that context path return 404 (the request never reaches a servlet), not 500. If this is the only application on the instance, the JVM is up, the connector is bound, and health checks that only test the port will pass while users see 404s.

The diagnostic structure looks like this:

flowchart TD
    A[WAR lands in webapps/] --> B[HostConfig.deployWAR]
    B --> C[Context init:
listeners, filters, servlets]
    C -->|listener or filter throws| D[LifecycleException:
Failed to start component]
    D --> E[catalina.out:
SEVERE wrapper only]
    D --> F[localhost.date.log:
full Caused-by chain]
    E --> G[FailedContext placeholder
state = FAILED]
    F --> H[Real root cause]
    G --> I[Manager:
FAIL - context failed to start]

Two practical consequences: the Manager responds with FAIL - Deployed application at context path [/yourapp] but context failed to start when you deploy via the text API, and Tomcat does not auto-retry. The context stays in FAILED until you redeploy or restart, and a restart hits the same exception unless the underlying cause (missing env var, unreachable database, wrong library version) is fixed.

Common causes

Quick checks

These are all read-only. None of them touch the running Tomcat.

# Confirm the context state via the Manager text API (Standalone Tomcat only)
curl -s -u $MANAGER_USER:$MANAGER_PASS \
  'http://localhost:8080/manager/text/list' | grep -i yourapp
# Expect: /yourapp:stopped:0 or similar non-running state (manager text/list reports only running|stopped)

# Pull the SEVERE wrapper context out of catalina.out
grep -n -B1 -A20 'HostConfig.deployWAR Error deploying' \
  $CATALINA_BASE/logs/catalina.out | head -60

# Find the real exception in today's localhost log
ls -la $CATALINA_BASE/logs/localhost.*.log
grep -n -A40 'One or more listeners failed to start\|Failed to start component\|NoSuchMethodError\|NoClassDefFoundError' \
  $CATALINA_BASE/logs/localhost.$(date +%Y-%m-%d).log | head -120

# Check WAR / exploded dir ownership against the Tomcat process user
ps -o user= -p $(pgrep -f 'catalina.startup.Bootstrap' | head -1)
ls -ld $CATALINA_BASE/webapps/yourapp $CATALINA_BASE/webapps/yourapp.war

# Confirm Tomcat major version (javax vs jakarta boundary)
$CATALINA_HOME/bin/version.sh | grep -i 'Server version'

# Check the host-level deployXML setting
grep -n 'Host ' $CATALINA_BASE/conf/server.xml | head
grep -n 'deployXML' $CATALINA_BASE/conf/server.xml $CATALINA_BASE/conf/context.xml

# Check whether the canonical cache workaround is set
grep -i 'useCanonCaches' $CATALINA_BASE/bin/setenv.sh $CATALINA_HOME/bin/catalina.sh 2>/dev/null

# Spot 404s landing on the failed context in the access log
grep ' /yourapp' $CATALINA_BASE/logs/localhost_access_log.$(date +%Y-%m-%d).txt | \
  awk '{print $9}' | sort | uniq -c

Embedded Tomcat (Spring Boot, etc.) does not have the Manager app and does not split logs the same way. The same LifecycleException appears in the application’s own logback or log4j output, usually with the full Caused by: chain inline. Look for Failed to start component and read down from there.

How to diagnose it

1. Confirm the context is actually FAILED. Use the Manager text API list command, or query the JMX bean Catalina:type=Context,host=localhost,context=/yourapp for state. The only healthy state is STARTED. Anything else means the application is not serving.
2. Stop reading catalina.out for the root cause. The wrapper tells you what failed at the container level, not why. Note the timestamp on the SEVERE line, then jump to localhost.<date>.log for the same time window.
3. Read the full Caused by: chain in localhost.<date>.log. The first exception is usually org.apache.catalina.core.StandardContext.startInternal failing because a listener failed. The interesting frame is two or three Caused by: levels down, where the application code, a framework initializer, or a classloader throws.
4. Classify the leaf exception. Map it to one of the cause classes in the table above:
   • NoClassDefFoundError: javax/servlet/... - namespace mismatch between the WAR and the Tomcat major version.
   • NoSuchMethodError in a known library - duplicate versions on the classpath.
   • SQLException, ConnectException, UnknownHostException - the application tried to reach a dependency at boot and failed.
   • IllegalArgumentException on a missing property or env var - the listener requires configuration that was not injected.
   • IllegalStateException: Unable to disable the global canonical file name cache - the Tomcat 10.1.35+ CVE-2024-56337 mitigation triggered.
5. Correlate with the deploy event. If you have CI/CD timestamps, compare the failing deploy with the last known-good deploy. Diff the WAR contents (unzip -l old.war > /tmp/old; unzip -l new.war > /tmp/new; diff /tmp/old /tmp/new). Most deployment-only failures come down to one changed library or one missing env var.

Metrics and signals to monitor

Fixes

javax to jakarta namespace mismatch

The most common deployment failure on Tomcat 10 and 11. A WAR built against the Java EE 8 javax.servlet:* APIs cannot load on Tomcat 10+ because those classes do not exist; the runtime is jakarta.servlet:*. The failure shows up as NoClassDefFoundError: javax/servlet/ServletRequestListener or any other javax/servlet/* class.

Fix options, in order of preference:

• Rebuild the WAR against jakarta.servlet:jakarta.servlet-api (5.0 for Tomcat 10, 6.0 for Tomcat 11) and republish. This is the only correct fix.
• Run the Tomcat Migration Tool for Jakarta EE on the existing WAR. It rewrites bytecode and descriptors from javax.* to jakarta.*. Test thoroughly; the tool handles the API rename but cannot fix code that depends on third-party libraries still on javax.*.
• Stay on Tomcat 9 if you cannot migrate. Note that end of support for Tomcat 9.0.x is expected no earlier than 31 March 2027.

Listener or filter startup failure

SEVERE: One or more listeners failed to start. Full details will be found in the container log. is the wrapper. The actual stack from ServletContextListener.contextInitialized() is in localhost.<date>.log, immediately above that line. Fix the underlying condition: inject the missing env var, restore the missing config file, or make the database reachable at boot. If the listener cannot tolerate a transiently unavailable dependency, wrap the init in a retry or fail fast with a clear message rather than letting Tomcat wrap a generic LifecycleException.

Library version conflict (NoSuchMethodError)

Two versions of the same artifact end up in WEB-INF/lib (or split between WEB-INF/lib and the Tomcat lib directory). The classloader loads one version; the calling code was compiled against another. Inspect the WAR contents:

# List every JAR in the WAR
unzip -l yourapp.war | grep 'WEB-INF/lib/.*\.jar'

# Find duplicates by artifact name across the WAR and Tomcat lib
ls $CATALINA_HOME/lib/*.jar > /tmp/tomcat-libs.txt
unzip -l yourapp.war | awk '/WEB-INF\/lib\/.*\.jar/ {print $4}' | \
  xargs -n1 basename > /tmp/war-libs.txt
# Compare the two lists

Resolve by excluding the conflicting transitive dependency in your build, or by moving shared libraries to the Tomcat lib directory with delegate="true" on the Loader. The first option is safer because it scopes the change to one application; the second changes classloading for every app on the instance.

Permission denied on WAR extraction

Tomcat must own the webapps directory and the exploded application directory to expand the WAR and write work files. If the Tomcat process runs as user tomcat and the WAR was copied in as root, the explosion fails partway through with FileNotFoundException ... (Permission denied), wrapped in the standard LifecycleException:

# Show the process user and the file ownership side by side
ps -o user= -p $(pgrep -f catalina.startup.Bootstrap | head -1)
ls -ld $CATALINA_BASE/webapps $CATALINA_BASE/webapps/yourapp $CATALINA_BASE/webapps/yourapp.war

Fix with chown -R tomcat:tomcat $CATALINA_BASE/webapps/yourapp* and clean the work directory for that context before redeploying. Add this to the deploy pipeline; the issue recurs every time a CI runner copies a WAR in as root.

DirResourceSet canonical cache failure (CVE-2024-56337)

On Tomcat 10.1.35 and later, DirResourceSet.initInternal() refuses to start unless the JVM has been told to disable canonical file name caching, which is the workaround for CVE-2024-56337. The failure looks like:

java.lang.IllegalStateException: Unable to disable the global canonical file name cache or confirm that it is disabled

Add the following to JAVA_OPTS (typically in setenv.sh):

JAVA_OPTS="$JAVA_OPTS -Dsun.io.useCanonCaches=false"

Restart the JVM for the flag to take effect. If you cannot change JVM flags, downgrade to a Tomcat version before the check was introduced (the check landed in 10.1.35), but the better path is to apply the JVM flag and stay current.

deployXML=false blocking context.xml

If the Host element in server.xml has deployXML="false", any WAR that bundles a META-INF/context.xml will fail deployment with the SEVERE message mentioning the deployXML setting. Either set deployXML="true" on the Host (the default), or remove the META-INF/context.xml from the WAR and define the resource at the Host or Global level instead. The right answer depends on whether you trust WAR authors to set container-level configuration.

Prevention

• Validate the namespace in CI. Add a build-time check that the WAR depends on jakarta.servlet:* for Tomcat 10+, never javax.servlet:*. Fail the build instead of failing the deploy.
• Pin the Tomcat version and the JVM flags together. Document the required JAVA_OPTS for each Tomcat minor version. The CVE-2024-56337 mitigation is one example; future CVEs will add more.
• Run deploys through staging with the same data shape. Most listener startup failures are environment-specific: a config file that exists in dev, an env var set by the deployment framework in prod but not in the promotion pipeline. Staging should fail the same way prod would.
• Set -XX:MaxMetaspaceSize. A failing init that leaks a classloader on every retry will eventually exhaust Metaspace. Without the limit, the process dies from OS OOM kill with no JVM-level error.
• Monitor context state, not just process state. The Tomcat JVM can be perfectly healthy while one application sits in FAILED. Health checks that hit the application’s own endpoint (not / and not a TCP connect) catch this.
• Keep the Manager app secured. The Manager is the easiest way to redeploy a failed context and the easiest way for an attacker to drop a webshell. Restrict it to localhost or remove it from production entirely.

How Netdata helps

• Per-second context-state tracking via JMX. Netdata’s Tomcat collector reads the Catalina:type=Context MBeans every second, so a transition from STARTED to FAILED shows up immediately, with the exact timestamp you need to line up against the deploy and the localhost.<date>.log entry.
• 404 rate on the application path. When a context lands in FAILED, the access-log 404 rate on that path spikes. Netdata surfaces access-log-derived metrics per second, which lets you distinguish a deploy-induced 404 burst from a crawler 404 pattern. See the related guide on separating server failures from crawler 404s.
• Deploy-time correlation. Anomaly detection on request throughput, error rate, and thread pool utilization around the deploy window narrows the search from “something broke” to “this exact deploy broke, here is the second it started failing.”
• Heap and Metaspace baselining. A failed init can shift the post-GC heap baseline or push Metaspace up if a classloader was leaked. Netdata’s per-pool JVM memory charts make both visible without a separate JMX tool.
• Log pattern alerts. Netdata can alert on the SEVERE [localhost-startStop- pattern in catalina.out, which is the canonical signature of a deploy-time failure, and on OutOfMemoryError: Metaspace for the longer-running classloader leak case.

Related guides

• Tomcat 5xx error rate: separating server failures from crawler 404s
• Tomcat accept queue overflow: acceptCount, somaxconn, and Recv-Q
• Tomcat access log setup: adding %D and %T for per-request latency
• Tomcat java.net.BindException: Address already in use: the connector never starts
• Tomcat average latency lies: why you need p95/p99 from the access log
• Tomcat threads blocked forever: the missing outbound timeout
• Tomcat classloader leak on redeploy: why the old WebappClassLoader never dies
• Tomcat connection refused: maxConnections and acceptCount both exhausted
• Tomcat accepts connections but never responds: the TCP-connect trap
• Tomcat file descriptor usage: OpenFileDescriptorCount vs the ulimit
• Tomcat frequent Full GC: pause time, G1, and the 5% overhead rule
• Tomcat GC death spiral: full GCs dominating and throughput collapsing