{"record":{"id":"8b4e6c1052dd2ee9","repo":"apache/hadoop","slug":"undefined-scheme-for-u","errorCode":null,"errorMessage":"Undefined scheme for \" + u","messagePattern":"Undefined scheme for \" \\+ u","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/namenode/NNStorage.java","lineNumber":377,"sourceCode":"          return sd;\n        }\n      }\n    } catch (IOException ioe) {\n      LOG.warn(\"Error converting file to URI\", ioe);\n    }\n    return null;\n  }\n\n  /**\n   * Checks the consistency of a URI, in particular if the scheme\n   * is specified.\n   * @param u URI whose consistency is being checked.\n   */\n  private static void checkSchemeConsistency(URI u) throws IOException {\n    String scheme = u.getScheme();\n    // the URI should have a proper scheme\n    if(scheme == null) {\n      throw new IOException(\"Undefined scheme for \" + u);\n    }\n  }\n\n  /**\n   * Retrieve current directories of type IMAGE.\n   * @return Collection of URI representing image directories\n   * @throws IOException in case of URI processing error\n   */\n  Collection<URI> getImageDirectories() throws IOException {\n    return getDirectories(NameNodeDirType.IMAGE);\n  }\n\n  /**\n   * Retrieve current directories of type EDITS.\n   * @return Collection of URI representing edits directories\n   * @throws IOException in case of URI processing error\n   */\n  Collection<URI> getEditsDirectories() throws IOException {","sourceCodeStart":359,"sourceCodeEnd":395,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/namenode/NNStorage.java#L359-L395","documentation":"NNStorage.checkSchemeConsistency rejects storage URIs whose scheme is null: NameNode storage and journal locations must resolve to a concrete scheme (file, hdfs, qjm), and an entry that parses as a URI-without-scheme is rejected during NNStorage setup. The message echoes the offending URI so the bad config line can be found directly.","triggerScenarios":"A dfs.namenode.edits.dir (or name.dir) entry like ':///data/edits' with an empty scheme, or programmatic construction that passes an already-built URI with null scheme into the NN storage setup (e.g. URI.create on a host-only or malformed string).","commonSituations":"Hand-edited hdfs-site.xml with a stray colon; XML variable substitution resolving to an empty value or scheme-only string; custom tooling building StorageDirectory URIs without normalization.","solutions":["Copy the URI from the message into the config fix: give it an explicit scheme - file:///abs/path, hdfs://nn:8020/..., qjm://jns/jid.","Run 'hdfs getconf -confKey dfs.namenode.edits.dir' and dfs.namenode.name.dir equivalents to see the post-substitution value the NN actually parses.","For local paths, prefer absolute paths starting with '/' so normalization can add the file: scheme for you."],"exampleFix":"// before - empty scheme from a bad substitution\n<property>\n  <name>dfs.namenode.edits.dir</name>\n  <value>${eds.scheme}:///data/edits</value>\n</property>\n\n// after - explicit scheme\n<property>\n  <name>dfs.namenode.edits.dir</name>\n  <value>file:///data/edits</value>\n</property>","handlingStrategy":"validation","validationCode":"// Config lint before first NN start\nfor (String key : Arrays.asList(\"dfs.namenode.name.dir\", \"dfs.namenode.edits.dir\",\n                                \"dfs.namenode.shared.edits.dir\")) {\n  for (String loc : conf.getTrimmedStrings(key)) {\n    if (loc == null || loc.isEmpty()) continue;\n    URI u;\n    try { u = URI.create(loc); } catch (IllegalArgumentException ex) { u = null; }\n    boolean ok = u != null && u.getScheme() != null;\n    if (!ok && !loc.startsWith(\"/\")) {\n      throw new IllegalArgumentException(key + \" entry lacks a scheme and is not an absolute path: \" + loc);\n    }\n  }\n}","typeGuard":"static boolean hasScheme(String location) {\n  if (location == null || location.isEmpty()) return false;\n  try {\n    return URI.create(location).getScheme() != null;\n  } catch (IllegalArgumentException e) {\n    return false;\n  }\n}","tryCatchPattern":"try {\n  URI u = resolveStorageUri(dir);\n  NNStorage.checkSchemeConsistency(u);\n} catch (IOException e) {\n  if (e.getMessage() != null && e.getMessage().startsWith(\"Undefined scheme for\")) {\n    throw new ConfigurationException(\"Storage URI needs an explicit scheme (file:///, hdfs://, qjm://): \" + e.getMessage(), e);\n  }\n  throw e;\n}","preventionTips":["Always write storage dirs with explicit schemes in production configs.","Lint hdfs-site.xml for empty-scheme values (':///' patterns) in CI.","Prefer absolute '/' paths for local dirs so Hadoop can normalize them to file: itself."],"tags":["hdfs","configuration","uri","storage"],"backgroundTag":"missing-uri-scheme","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}