Tomcat context in FAILED state: the app is down but Tomcat looks healthy

Your monitoring says Tomcat is up. The JVM process is running, the HTTP connector accepts TCP connections, and a curl to port 8080 returns an HTTP response. But every request to the application returns 404, and users cannot reach any endpoint.

This is the signature of a context in FAILED or STOPPED state. Tomcat continues running. The connectors keep listening. Other deployed contexts keep serving. But the failed context’s servlet mappings are inactive, so every request to it returns 404. From the outside, it looks like a missing route or an undeployed application.

The trap is twofold. First, process-alive and port-listening health checks pass, so your uptime monitor says green. Second, the Tomcat Manager text/list output does not expose a FAILED state. It reports the context as stopped, with no distinction between an operator who intentionally stopped the app and a context that threw during startup. The reliable API signal is the stateName attribute on the Context MBean, and the reliable root-cause signal is the startup exception in catalina.out or localhost.<date>.log.

What this means

Tomcat organizes applications as Context components nested inside a Host. Each context has a lifecycle state from the LifecycleState enum: NEW, STARTING_PREP, STARTING, STARTED, STOPPING, STOPPED, FAILED, and a few others. A context must reach STARTED for its servlet mappings, filters, and listeners to be active.

When a context fails during startup, LifecycleBase sets the state to FAILED and then calls stop() internally, which transitions the component to STOPPED. The parent Host continues starting normally. Tomcat may substitute a FailedContext placeholder for the failed StandardContext so the Host can proceed without the failed child blocking it.

stateDiagram-v2
    [*] --> NEW
    NEW --> STARTING: deploy / start
    STARTING --> STARTED: init succeeds
    STARTING --> FAILED: init throws exception
    FAILED --> STOPPED: LifecycleBase calls stop
    STARTED --> STOPPING: operator stop
    STOPPING --> STOPPED

Requests to a stopped or failed context return 404 because the servlet mapping was never registered. The request never reaches application code. There is no 500, no 503, no exception propagated to the client. From the servlet container’s perspective, the path does not exist.

Tomcat does not auto-restart failed contexts. Once a context enters FAILED and transitions to STOPPED, it stays there until an operator explicitly triggers a start or reload via the Manager, or Tomcat itself is restarted. There is no retry mechanism: the startup failure is assumed to be deterministic.

Common causes

Quick checks

Run these read-only checks to confirm the diagnosis without disrupting anything.

# Check Tomcat process is alive
pgrep -f 'org.apache.catalina.startup.Bootstrap' || echo "DOWN"

# Check connector is listening on 8080
ss -tnl 'sport = :8080'

# List all deployed contexts and their Manager-reported state.
# Requires a user with the manager-script role.
# Output format: /<context-path>:<running|stopped>:<sessions>:<docBase>
curl -s -u "$USER:$PASS" 'http://localhost:8080/manager/text/list'

# Query the Context MBean lifecycle state via the Manager JMX proxy.
# Requires a user with the manager-jmx role.
# Returns stateName: STARTED, STOPPED, FAILED, etc.
curl -s -u "$USER:$PASS" \
  'http://localhost:8080/manager/jmxproxy/?get=Catalina:type=Context,host=localhost,context=/myapp&att=stateName'

# Check catalina.out for startup failure markers
grep -i -A 30 'listenerStart\|filterStart\|Context.*startup failed\|Error initializing' \
  "$CATALINA_BASE/logs/catalina.out" | tail -100

# Check localhost log for context init errors
tail -100 "$CATALINA_BASE/logs/localhost.$(date +%Y-%m-%d).log"

# Test the app endpoint vs a known-good endpoint
curl -s -o /dev/null -w "%{http_code}" http://localhost:8080/myapp/
curl -s -o /dev/null -w "%{http_code}" http://localhost:8080/manager/text/list

If $CATALINA_BASE is not set in your shell, check the Tomcat startup script or systemd unit for the actual log path. It is often /var/log/tomcat9/ or /opt/tomcat/logs/ depending on your distribution and installation method.

The Manager text/list output shows only two states: running or stopped. A context that failed during startup appears as stopped. There is no failed value in the list output across any supported Tomcat version (8.5 through 11.0). If you see /myapp:stopped:0:myapp and you did not intentionally stop the app, it almost certainly failed during startup.

The Manager JMX proxy is the easiest way to query the Context MBean without configuring remote JMX. The stateName attribute returns the full lifecycle state string. A value of FAILED confirms the context failed during initialization. A value of STOPPED means the failed-start path has completed (LifecycleBase already called stop()) or the context was manually stopped. In practice, by the time you check, you will most likely see STOPPED, because the transition from FAILED to STOPPED happens automatically and quickly. If the JMX proxy returns FAIL - no MBean found, the context object may not exist at all (the context was never registered or was fully undeployed).

If the Manager app is not deployed, use jmxterm or jconsole against a local or remote JMX endpoint. Remote JMX requires JVM flags like -Dcom.sun.management.jmxremote.port=9090 on the Tomcat process; Tomcat does not expose a remote JMX port by default.

If you are running Spring Boot with embedded Tomcat, the Manager app is absent. Use JMX for context state and application logs for startup exceptions. Note that Spring Boot 2.2.0+ disables the Tomcat MBean registry by default (server.tomcat.mbeanregistry.enabled=false), which prevents JMX queries against Context MBeans entirely. Enable it explicitly if you depend on JMX for lifecycle monitoring.

How to diagnose it

1. Confirm the symptom pattern. Curl the application endpoint. If you get 404 and the Manager endpoint or a different context returns 200, the connectors and Tomcat are fine. The problem is scoped to one context.

2. Check Manager text/list. Look for the target context showing as stopped. If you expected running, this confirms the app is not serving.

3. Query the Context MBean. Use the Manager JMX proxy or jmxterm to check stateName. A value of STOPPED or FAILED confirms the context is not running.

4. Find the exception in the logs. The startup exception is the root cause. Check catalina.out first for the stack trace, then localhost.<date>.log for ServletContextListener failures. The exception typically appears near a SEVERE: Error listenerStart or SEVERE: Context [/myapp] startup failed due to previous errors line in catalina.out.

5. Correlate with deployment timing. Check when the WAR file was last modified or deployed. If the failure started right after a deployment, the root cause is likely in the new build: a classpath conflict, a missing config value, or a failed database migration.

6. Check external dependencies at startup time. If the exception is a connection failure, verify whether the database or service the app needs was reachable from the Tomcat host at the moment of startup. A transient dependency outage during deployment is a common cause that resolves itself, but the context remains stopped until you redeploy.

Metrics and signals to monitor

Fixes

Fix the root cause, then redeploy

The startup exception in the logs tells you what went wrong. Common remediations:

• Missing database or service: Start or restore the dependency, then redeploy the WAR or restart Tomcat. Tomcat redeploys all WAR files in webapps on restart regardless of autoDeploy settings.
• Missing configuration: Add the missing property, environment variable, or JNDI resource definition to the correct context.xml or server.xml, then redeploy.
• Classpath conflict: Resolve the version mismatch in the build. Use mvn dependency:tree or gradle dependencies to find conflicting transitive dependencies. Rebuild and redeploy.
• ServletContextListener failure: Fix the listener code that throws during contextInitialized. Common culprits are missing null checks on configuration values, connection pool initialization failures, and scheduler setup errors.

Start the stopped context via Manager

After fixing the root cause, you can start the stopped context without restarting the entire Tomcat instance:

# Start a stopped context (requires Manager app, manager-script role)
curl -s -u "$USER:$PASS" 'http://localhost:8080/manager/text/start?path=/myapp'

This re-triggers the context lifecycle. If the root cause is not actually fixed, the context fails again and returns to STOPPED. Check the response for OK or FAIL.

Restart Tomcat

A full Tomcat restart re-runs deployment for all WARs in webapps. Use this when multiple contexts are affected or when you need a clean slate.

# WARNING: drops all in-flight requests and restarts every context.
# Service name varies by distribution (tomcat, tomcat9, tomcat@9, etc.).
systemctl restart tomcat

After restart, check the Manager list and the startup logs to confirm all expected contexts reached STARTED. Do not assume success from the process-alive check alone.

Prevention

• Health check the application, not the connector. A TCP connect to port 8080 tells you the connector is listening, not that any application is running. Point your health check at an application-specific endpoint that exercises the app’s critical dependencies. If the context is stopped, this endpoint returns 404, which your health check should treat as unhealthy.
• Monitor context state via JMX. Poll the stateName attribute on each production Context MBean. Alert on any value other than STARTED. This catches failed contexts that your process-alive check will never see.
• Parse the access log for context-scoped 404 spikes. If 404s for a specific context path jump from near-zero to 100% of requests, the context is likely stopped or failed. Filter by request path prefix, not just by overall error rate.
• Run smoke tests after every deployment. After deploying a WAR, curl a known application endpoint and check for 200. If you get 404, the context failed to start. Do not rely on the Tomcat deployment success message alone: it confirms the WAR was processed but does not guarantee the context reached STARTED.

How Netdata helps

Netdata’s JMX collector can poll the Context MBean stateName attribute per second and alert when any production context leaves the STARTED state, catching the failure before users report 404s. Access log metrics show per-context 404 rates and request throughput, making the “Tomcat is up but the app is down” pattern visible without correlating across multiple tools. Correlating the context state change with the WAR deploy timestamp narrows the cause to the new build.

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