apache/hadoop · critical · IllegalArgumentException

System property [{0}] not defined

Error message

System property [{0}] not defined

What it means

ServerWebApp.getHomeDir() resolves the webapp home directory from a thread-local (set only in tests) or from the Java system property '<serverName>.home.dir' (e.g. 'httpfs.home.dir'). If neither is set it throws IllegalArgumentException('System property [httpfs.home.dir] not defined') during servlet context initialization, so the webapp fails to deploy.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs-httpfs/src/main/java/org/apache/hadoop/lib/servlet/ServerWebApp.java:125

  }

  /**
   * Returns the server home directory.
   * <p>
   * It is looked up in the Java System property
   * <code>#SERVER_NAME#.home.dir</code>.
   *
   * @param name the server home directory.
   *
   * @return the server home directory.
   */
  static String getHomeDir(String name) {
    String homeDir = HOME_DIR_TL.get();
    if (homeDir == null) {
      String sysProp = name + HOME_DIR;
      homeDir = System.getProperty(sysProp);
      if (homeDir == null) {
        throw new IllegalArgumentException(MessageFormat.format(
            "System property [{0}] not defined", sysProp));
      }
    }
    return homeDir;
  }

  /**
   * Convenience method that looks for Java System property defining a
   * diretory and if not present defaults to the specified directory.
   *
   * @param name server name, used as prefix of the Java System property.
   * @param dirType dir type, use as postfix of the Java System property.
   * @param defaultDir the default directory to return if the Java System
   * property <code>name + dirType</code> is not defined.
   *
   * @return the directory defined in the Java System property or the
   *         the default directory if the Java System property is not defined.
   */

View on GitHub (pinned to 2add963021)

Solutions

  1. Start httpfs via the standard script (httpfs.sh / httpfs-run.sh) which defines all required system properties
  2. Or pass -Dhttpfs.home.dir=/opt/httpfs-<version>/httpfs/webapp (plus config/log/temp dir properties) to the JVM
  3. In tests, call ServerWebApp.setHomeDirForTesting(...) before initializing the webapp
  4. Redeploy after fixing the JVM options

Example fix

# before
java -jar tomcat.jar --webapps httpfs.war   # missing properties -> IllegalArgumentException

# after
java -Dhttpfs.home.dir=$HTTPFS_HOME/webapp \
     -Dhttpfs.config.dir=$HTTPFS_CONF -Dhttpfs.log.dir=$HTTPFS_LOG \
     -Dhttpfs.temp.dir=$HTTPFS_TEMP ...
Defensive patterns

Strategy: validation

Validate before calling

for (String prop : new String[]{
     "httpfs.home.dir", "httpfs.config.dir", "httpfs.log.dir", "httpfs.temp.dir",
     "httpfs.http.hostname", "httpfs.http.port"}) {
  if (System.getProperty(prop) == null) {
    throw new IllegalStateException("missing required system property: " + prop);
  }
}

Try / catch

try {
  new ServerWebApp("httpfs").contextInitialized(null);
} catch (IllegalArgumentException ex) {
  if (ex.getMessage().contains("not defined")) {
    // missing bootstrap property - fix JVM options before retry
    log.error("bootstrap property missing: {}", ex.getMessage());
  }
  throw ex;
}

Prevention

When it happens

Trigger: Starting the httpfs war without the -Dhttpfs.home.dir=<path> JVM property and without ServerWebApp.setHomeDirForTesting(); resolveDir() throws during ServerWebApp.contextInitialized, aborting deployment in the servlet container.

Common situations: Running the httpfs war in a foreign/different Tomcat instead of the bundled scripts (httpfs.sh sets the property); unit tests embedding ServerWebApp without setting the thread-local home dir; a launch wrapper that drops JVM -D options.

Related errors

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