apache/hadoop · critical · RuntimeException

System property 'kms.config.dir' must be an absolute path: %

Error message

System property 'kms.config.dir' must be an absolute path: %s

What it means

KMS locates its configuration files via the JVM system property kms.config.dir (set by the kms.sh / hadoop-kms startup scripts). In KMSConfiguration.getConfiguration (KMSConfiguration.java:120), if that path is not URI-absolute (Path.isUriPathAbsolute() false), KMS throws RuntimeException "System property 'kms.config.dir' must be an absolute path: <value>" — relative directories like 'kms-config' or 'conf/' are rejected so that file:// resource URLs can be built reliably.

Source

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

  public static final String KEY_AUTHORIZATION_ENABLE = CONFIG_PREFIX +
      "key.authorization.enable"; 

  public static final boolean KEY_AUTHORIZATION_ENABLE_DEFAULT = true;

  static {
    Configuration.addDefaultResource(KMS_DEFAULT_XML);
    Configuration.addDefaultResource(KMS_SITE_XML);
  }

  static Configuration getConfiguration(boolean loadHadoopDefaults,
      String ... resources) {
    Configuration conf = new Configuration(loadHadoopDefaults);
    String confDir = System.getProperty(KMS_CONFIG_DIR);
    if (confDir != null) {
      try {
        Path confPath = new Path(confDir);
        if (!confPath.isUriPathAbsolute()) {
          throw new RuntimeException("System property '" + KMS_CONFIG_DIR +
              "' must be an absolute path: " + confDir);
        }
        for (String resource : resources) {
          conf.addResource(new URL("file://" + new Path(confDir, resource).toUri()));
        }
      } catch (MalformedURLException ex) {
        throw new RuntimeException(ex);
      }
    } else {
      for (String resource : resources) {
        conf.addResource(resource);
      }
    }
    return conf;
  }

  public static Configuration getKMSConf() {
    return getConfiguration(true, "core-site.xml", KMS_SITE_XML);

View on GitHub (pinned to 2add963021)

Solutions

1. Set kms.config.dir to an absolute path, e.g. KMS_CONFIG_DIR=/etc/hadoop-kms/conf in kms-env.sh (the stock scripts use /etc/hadoop-kms/conf)
2. If you launch the server manually, pass -Dkms.config.dir=/abs/path on the java command line
3. In Docker/containers, resolve the path at image build time to a fixed absolute location such as /etc/hadoop-kms/conf

Example fix

# kms-env.sh before
export KMS_CONFIG_DIR=kms-conf
# after
export KMS_CONFIG_DIR=/etc/hadoop-kms/conf

// In custom launchers: canonicalize before setting the property
String dir = args[0];
File f = new File(dir);
if (!f.isAbsolute()) dir = f.getAbsolutePath();
if (!f.exists()) throw new IllegalStateException("kms.config.dir does not exist: " + dir);
System.setProperty("kms.config.dir", dir);

When it happens

Trigger: Starting the KMS with -Dkms.config.dir set to a relative path (e.g. editing kms-env.sh to KMS_CONFIG_DIR=kms-conf instead of /etc/hadoop-kms/conf, or launching Tomcat/Jetty by hand with a relative -D flag). The check runs while loading kms-site.xml / kms-acls.xml / kms-default.xml at webapp startup, so the KMS fails immediately to deploy.

Common situations: Custom launch wrappers that compute the config dir relative to CWD; Docker images where the workdir differs from the intended absolute path; symlinks or env-var expansion ($KMS_CONFIG_DIR) yielding an empty or relative string; porting scripts between distributions that use different absolute prefixes.

Related errors

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

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