{"record":{"id":"8d805e0eb1efe58f","repo":"apache/hadoop","slug":"system-property-0-not-defined","errorCode":null,"errorMessage":"System property [{0}] not defined","messagePattern":"System property \\[(.+?)\\] not defined","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"critical","filePath":"hadoop-hdfs-project/hadoop-hdfs-httpfs/src/main/java/org/apache/hadoop/lib/servlet/ServerWebApp.java","lineNumber":125,"sourceCode":"  }\n\n  /**\n   * Returns the server home directory.\n   * <p>\n   * It is looked up in the Java System property\n   * <code>#SERVER_NAME#.home.dir</code>.\n   *\n   * @param name the server home directory.\n   *\n   * @return the server home directory.\n   */\n  static String getHomeDir(String name) {\n    String homeDir = HOME_DIR_TL.get();\n    if (homeDir == null) {\n      String sysProp = name + HOME_DIR;\n      homeDir = System.getProperty(sysProp);\n      if (homeDir == null) {\n        throw new IllegalArgumentException(MessageFormat.format(\n            \"System property [{0}] not defined\", sysProp));\n      }\n    }\n    return homeDir;\n  }\n\n  /**\n   * Convenience method that looks for Java System property defining a\n   * diretory and if not present defaults to the specified directory.\n   *\n   * @param name server name, used as prefix of the Java System property.\n   * @param dirType dir type, use as postfix of the Java System property.\n   * @param defaultDir the default directory to return if the Java System\n   * property <code>name + dirType</code> is not defined.\n   *\n   * @return the directory defined in the Java System property or the\n   *         the default directory if the Java System property is not defined.\n   */","sourceCodeStart":107,"sourceCodeEnd":143,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs-httpfs/src/main/java/org/apache/hadoop/lib/servlet/ServerWebApp.java#L107-L143","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Start httpfs via the standard script (httpfs.sh / httpfs-run.sh) which defines all required system properties","Or pass -Dhttpfs.home.dir=/opt/httpfs-<version>/httpfs/webapp (plus config/log/temp dir properties) to the JVM","In tests, call ServerWebApp.setHomeDirForTesting(...) before initializing the webapp","Redeploy after fixing the JVM options"],"exampleFix":"# before\njava -jar tomcat.jar --webapps httpfs.war   # missing properties -> IllegalArgumentException\n\n# after\njava -Dhttpfs.home.dir=$HTTPFS_HOME/webapp \\\n     -Dhttpfs.config.dir=$HTTPFS_CONF -Dhttpfs.log.dir=$HTTPFS_LOG \\\n     -Dhttpfs.temp.dir=$HTTPFS_TEMP ...","handlingStrategy":"validation","validationCode":"for (String prop : new String[]{\n     \"httpfs.home.dir\", \"httpfs.config.dir\", \"httpfs.log.dir\", \"httpfs.temp.dir\",\n     \"httpfs.http.hostname\", \"httpfs.http.port\"}) {\n  if (System.getProperty(prop) == null) {\n    throw new IllegalStateException(\"missing required system property: \" + prop);\n  }\n}","typeGuard":null,"tryCatchPattern":"try {\n  new ServerWebApp(\"httpfs\").contextInitialized(null);\n} catch (IllegalArgumentException ex) {\n  if (ex.getMessage().contains(\"not defined\")) {\n    // missing bootstrap property - fix JVM options before retry\n    log.error(\"bootstrap property missing: {}\", ex.getMessage());\n  }\n  throw ex;\n}","preventionTips":["Always launch via the bundled httpfs scripts instead of raw container deployment","Codify the full -D property set in the deployment descriptor/podspec","In tests, use ServerWebApp.setHomeDirForTesting() instead of relying on system properties"],"tags":["httpfs","system-property","startup","servlet","deployment"],"backgroundTag":"missing-system-property","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}