{"record":{"id":"dd361af24e79b890","repo":"apache/hadoop","slug":"system-property-kms-config-dir-must-be-an-absolu","errorCode":null,"errorMessage":"System property 'kms.config.dir' must be an absolute path: %s","messagePattern":"System property 'kms\\.config\\.dir' must be an absolute path: (.+?)","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":120,"sourceCode":"  public static final String KEY_AUTHORIZATION_ENABLE = CONFIG_PREFIX +\n      \"key.authorization.enable\"; \n\n  public static final boolean KEY_AUTHORIZATION_ENABLE_DEFAULT = true;\n\n  static {\n    Configuration.addDefaultResource(KMS_DEFAULT_XML);\n    Configuration.addDefaultResource(KMS_SITE_XML);\n  }\n\n  static Configuration getConfiguration(boolean loadHadoopDefaults,\n      String ... resources) {\n    Configuration conf = new Configuration(loadHadoopDefaults);\n    String confDir = System.getProperty(KMS_CONFIG_DIR);\n    if (confDir != null) {\n      try {\n        Path confPath = new Path(confDir);\n        if (!confPath.isUriPathAbsolute()) {\n          throw new RuntimeException(\"System property '\" + KMS_CONFIG_DIR +\n              \"' must be an absolute path: \" + confDir);\n        }\n        for (String resource : resources) {\n          conf.addResource(new URL(\"file://\" + new Path(confDir, resource).toUri()));\n        }\n      } catch (MalformedURLException ex) {\n        throw new RuntimeException(ex);\n      }\n    } else {\n      for (String resource : resources) {\n        conf.addResource(resource);\n      }\n    }\n    return conf;\n  }\n\n  public static Configuration getKMSConf() {\n    return getConfiguration(true, \"core-site.xml\", KMS_SITE_XML);","sourceCodeStart":102,"sourceCodeEnd":138,"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#L102-L138","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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)","If you launch the server manually, pass -Dkms.config.dir=/abs/path on the java command line","In Docker/containers, resolve the path at image build time to a fixed absolute location such as /etc/hadoop-kms/conf"],"exampleFix":"# kms-env.sh before\nexport KMS_CONFIG_DIR=kms-conf\n# after\nexport KMS_CONFIG_DIR=/etc/hadoop-kms/conf","handlingStrategy":"validation","validationCode":"// In custom launchers: canonicalize before setting the property\nString dir = args[0];\nFile f = new File(dir);\nif (!f.isAbsolute()) dir = f.getAbsolutePath();\nif (!f.exists()) throw new IllegalStateException(\"kms.config.dir does not exist: \" + dir);\nSystem.setProperty(\"kms.config.dir\", dir);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always configure KMS_CONFIG_DIR as an absolute path in kms-env.sh","In Docker, use fixed absolute paths like /etc/hadoop-kms/conf","Add a startup smoke test asserting the property is absolute"],"tags":["hadoop-kms","configuration","startup-failure","path-error"],"backgroundTag":"config-path-must-be-absolute","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}