{"record":{"id":"5268d3c3464d8117","repo":"apache/hadoop","slug":"system-property-kms-config-dir-not-defined","errorCode":null,"errorMessage":"System property 'kms.config.dir' not defined","messagePattern":"System property 'kms\\.config\\.dir' not defined","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"critical","filePath":"hadoop-common-project/hadoop-kms/src/main/java/org/apache/hadoop/crypto/key/kms/server/KMSConfiguration.java","lineNumber":172,"sourceCode":"      File f = new File(confDir, KMS_ACLS_XML);\n      LOG.trace(\"Checking file {}, modification time is {}, last reload time is\"\n          + \" {}\", f.getPath(), f.lastModified(), time);\n      // at least 100ms newer than time, we do this to ensure the file\n      // has been properly closed/flushed\n      newer = f.lastModified() - time > 100;\n    }\n    return newer;\n  }\n\n  /**\n   * Validate whether \"kms.config.dir\" and \"log4j.configuration\" are defined in the System\n   * properties. If not, abort the KMS WebServer.\n   */\n  public static void validateSystemProps() {\n    if (System.getProperty(KMS_CONFIG_DIR) == null) {\n      String errorMsg = \"System property '\" + KMS_CONFIG_DIR + \"' not defined\";\n      System.err.println(\"Aborting KMSWebServer because \" + errorMsg);\n      throw new RuntimeException(errorMsg);\n    }\n    if (System.getProperty(\"log4j.configuration\") == null) {\n      String errorMsg = \"System property 'log4j.configuration' not defined\";\n      System.err.println(\"Aborting KMSWebServer because \" + errorMsg);\n      throw new RuntimeException(errorMsg);\n    }\n  }\n}\n","sourceCodeStart":154,"sourceCodeEnd":181,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-common-project/hadoop-kms/src/main/java/org/apache/hadoop/crypto/key/kms/server/KMSConfiguration.java#L154-L181","documentation":"KMSWebServer calls KMSConfiguration.validateSystemProps (KMSConfiguration.java:172) before booting: if the JVM system property kms.config.dir is unset, it prints 'Aborting KMSWebServer because System property kms.config.dir not defined' to stderr and throws RuntimeException, aborting startup. The stock hadoop-kms scripts always set this property; its absence means the server is being launched outside those scripts.","triggerScenarios":"Starting the KMS jar/webapp directly with java -jar / a custom Tomcat instead of kms.sh start, or a broken kms-env.sh where KMS_CONFIG_DIR is empty so the -Dkms.config.dir flag never reaches the JVM.","commonSituations":"Containerized or systemd launches that bypass the wrapper scripts; env-var expansion failures (unset KMS_CONFIG_DIR); script edits that accidentally dropped the JAVA_OPTS entry.","solutions":["Start KMS via the provided script: $HADOOP_HOME/sbin/kms.sh start (or your distro's hadoop-kms service), which sets the property","If launching manually, add -Dkms.config.dir=/etc/hadoop-kms/conf (absolute path) to the java invocation","Verify kms-env.sh actually exports KMS_CONFIG_DIR and that the script that builds JAVA_OPTS is sourced"],"exampleFix":"# before\njava -jar webapps/kms.war\n# after\njava -Dkms.config.dir=/etc/hadoop-kms/conf -jar webapps/kms.war","handlingStrategy":"validation","validationCode":"// Before starting KMSWebServer programmatically\nif (System.getProperty(\"kms.config.dir\") == null)\n  throw new IllegalStateException(\"pass -Dkms.config.dir=<absolute conf dir>\");","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Use the shipped kms.sh/hadoop-kms launcher rather than raw java","Unit-test your custom launcher for both required -D flags","Document both mandatory properties (kms.config.dir, log4j.configuration) in runbooks"],"tags":["hadoop-kms","configuration","startup-failure","missing-system-property"],"backgroundTag":"missing-system-property","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-23T01:17:44.959Z"}