apache/hadoop · critical · RuntimeException

System property 'kms.config.dir' not defined

Error message

System property 'kms.config.dir' not defined

What it means

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.

Source

Thrown at hadoop-common-project/hadoop-kms/src/main/java/org/apache/hadoop/crypto/key/kms/server/KMSConfiguration.java:172

      File f = new File(confDir, KMS_ACLS_XML);
      LOG.trace("Checking file {}, modification time is {}, last reload time is"
          + " {}", f.getPath(), f.lastModified(), time);
      // at least 100ms newer than time, we do this to ensure the file
      // has been properly closed/flushed
      newer = f.lastModified() - time > 100;
    }
    return newer;
  }

  /**
   * Validate whether "kms.config.dir" and "log4j.configuration" are defined in the System
   * properties. If not, abort the KMS WebServer.
   */
  public static void validateSystemProps() {
    if (System.getProperty(KMS_CONFIG_DIR) == null) {
      String errorMsg = "System property '" + KMS_CONFIG_DIR + "' not defined";
      System.err.println("Aborting KMSWebServer because " + errorMsg);
      throw new RuntimeException(errorMsg);
    }
    if (System.getProperty("log4j.configuration") == null) {
      String errorMsg = "System property 'log4j.configuration' not defined";
      System.err.println("Aborting KMSWebServer because " + errorMsg);
      throw new RuntimeException(errorMsg);
    }
  }
}

View on GitHub (pinned to 2add963021)

Solutions

1. Start KMS via the provided script: $HADOOP_HOME/sbin/kms.sh start (or your distro's hadoop-kms service), which sets the property
2. If launching manually, add -Dkms.config.dir=/etc/hadoop-kms/conf (absolute path) to the java invocation
3. Verify kms-env.sh actually exports KMS_CONFIG_DIR and that the script that builds JAVA_OPTS is sourced

Example fix

# before
java -jar webapps/kms.war
# after
java -Dkms.config.dir=/etc/hadoop-kms/conf -jar webapps/kms.war

// Before starting KMSWebServer programmatically
if (System.getProperty("kms.config.dir") == null)
  throw new IllegalStateException("pass -Dkms.config.dir=<absolute conf dir>");

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• System property 'log4j.configuration' not defined
• Failed to load %s, please check configuration hadoop.kms.aud
• Failed to initialize %s
• System property 'kms.config.dir' must be an absolute path: %
• No KeyProvider has been defined

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