apache/hadoop · critical · RuntimeException

System property 'log4j.configuration' not defined

Error message

System property 'log4j.configuration' not defined

What it means

The second half of KMSConfiguration.validateSystemProps (KMSConfiguration.java:177): if the JVM system property log4j.configuration is unset, KMS prints 'Aborting KMSWebServer because System property log4j.configuration not defined' and throws RuntimeException. KMS requires an explicit log4j config so logging is deterministic under its embedded server; the stock scripts point it at the kms.log4j.properties in the config dir.

Source

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

      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 with the stock kms.sh / hadoop-kms scripts, which set -Dlog4j.configuration=<confdir>/kms.log4j.properties
2. When launching manually, pass both -Dkms.config.dir=/etc/hadoop-kms/conf and -Dlog4j.configuration=/etc/hadoop-kms/conf/kms.log4j.properties
3. Confirm the referenced log4j properties file exists at that path

Example fix

# before
java -Dkms.config.dir=/etc/hadoop-kms/conf -jar kms.war
# after
java -Dkms.config.dir=/etc/hadoop-kms/conf \
  -Dlog4j.configuration=/etc/hadoop-kms/conf/kms.log4j.properties \
  -jar kms.war

if (System.getProperty("log4j.configuration") == null)
  System.setProperty("log4j.configuration", confDir + "/kms.log4j.properties");

When it happens

Trigger: Launching the KMS without the wrapper scripts so -Dlog4j.configuration=... is never passed; or a launcher that only sets kms.config.dir but not the log4j property. Both properties are mandatory for KMSWebServer to boot.

Common situations: Custom systemd/Docker launches; upgrading scripts that drop the log4j flag; switching to log4j2-only environments where the legacy property is considered obsolete but this KMS version still demands it.

Related errors

• System property 'kms.config.dir' 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/adf0410c2953205c. Report an issue: GitHub.