What causes "Unable to initialize WebAppContext" in apache/hadoop?

Read the cause attached to this IOException - it is the actual context init failure with its stack trace

apache/hadoop · error · IOException

Unable to initialize WebAppContext

Error message

Unable to initialize WebAppContext

What it means

If the webapp's WebAppContext initialized but ended up unavailable (Jetty's getUnavailableException() non-null), HttpServer2 stops the whole server first (to kill Jetty's non-daemon threads) and then throws IOException 'Unable to initialize WebAppContext' with the unavailable throwable as the cause. Typical causes are web.xml errors, missing servlet/listener classes, or JSP/tag compile failures in the webapp.

Source

Thrown at hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/http/HttpServer2.java:1485

      } catch (MultiException ex) {
        LOG.info("HttpServer.start() threw a MultiException", ex);
        throw ex;
      }
      // Make sure there is no handler failures.
      Handler[] hs = webServer.getHandlers();
      for (Handler handler : hs) {
        if (handler.isFailed()) {
          throw new IOException(
              "Problem in starting http server. Server handlers failed");
        }
      }
      // Make sure there are no errors initializing the context.
      Throwable unavailableException = webAppContext.getUnavailableException();
      if (unavailableException != null) {
        // Have to stop the webserver, or else its non-daemon threads
        // will hang forever.
        webServer.stop();
        throw new IOException("Unable to initialize WebAppContext",
            unavailableException);
      }
    } catch (IOException e) {
      throw e;
    } catch (InterruptedException e) {
      throw (IOException) new InterruptedIOException(
          "Interrupted while starting HTTP server").initCause(e);
    } catch (Exception e) {
      throw new IOException("Problem starting http server", e);
    }
  }

  private void loadListeners() {
    for (Connector c : listeners) {
      webServer.addConnector(c);
    }
  }

View on GitHub (pinned to 2add963021)

Solutions

Read the cause attached to this IOException - it is the actual context init failure with its stack trace
Verify every class named in the webapp's web.xml and every context listener is on the daemon classpath
Confirm webapps/<app> resources are complete and the web.xml parses
If a custom webapp is at fault, remove/disable it to bring the daemon up, then fix it separately

Defensive patterns

Strategy: try-catch

Try / catch

try {
  httpServer.start();
} catch (IOException e) {
  if ("Unable to initialize WebAppContext".equals(e.getMessage())) {
    Throwable root = e.getCause(); // the context's unavailableException - real cause
    // fix web.xml / listener / classpath issues named there
  }
}

Prevention

Validate web.xml classes and listeners at build time
Keep custom webapps simple and covered by startup smoke tests
After packaging changes, diff the webapps resources shipped before and after

When it happens

Trigger: web.xml referencing a class not on the classpath; a ServletContextListener (e.g., Hadoop's own or a custom one) throwing during contextInitialized; missing webapps static resources after packaging changes; JSP compilation problems on exotic JDK versions.

Common situations: Custom webapps added to a daemon; upgrading Jetty/JDK where a listener becomes incompatible; packaging changes (see also 'webapps not found in CLASSPATH') that half-deploy a webapp.

Related errors

AI-assisted analysis of apache/hadoop@2add963021 (2026-08-22). Data as JSON: /api/errors/8a460fe5c55e25d9. Report an issue: GitHub.