apache/hadoop · error · IOException

Undefined scheme for " + u

Error message

Undefined scheme for " + u

What it means

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.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/namenode/NNStorage.java:377

          return sd;
        }
      }
    } catch (IOException ioe) {
      LOG.warn("Error converting file to URI", ioe);
    }
    return null;
  }

  /**
   * Checks the consistency of a URI, in particular if the scheme
   * is specified.
   * @param u URI whose consistency is being checked.
   */
  private static void checkSchemeConsistency(URI u) throws IOException {
    String scheme = u.getScheme();
    // the URI should have a proper scheme
    if(scheme == null) {
      throw new IOException("Undefined scheme for " + u);
    }
  }

  /**
   * Retrieve current directories of type IMAGE.
   * @return Collection of URI representing image directories
   * @throws IOException in case of URI processing error
   */
  Collection<URI> getImageDirectories() throws IOException {
    return getDirectories(NameNodeDirType.IMAGE);
  }

  /**
   * Retrieve current directories of type EDITS.
   * @return Collection of URI representing edits directories
   * @throws IOException in case of URI processing error
   */
  Collection<URI> getEditsDirectories() throws IOException {

View on GitHub (pinned to 2add963021)

Solutions

  1. Copy the URI from the message into the config fix: give it an explicit scheme - file:///abs/path, hdfs://nn:8020/..., qjm://jns/jid.
  2. Run 'hdfs getconf -confKey dfs.namenode.edits.dir' and dfs.namenode.name.dir equivalents to see the post-substitution value the NN actually parses.
  3. For local paths, prefer absolute paths starting with '/' so normalization can add the file: scheme for you.

Example fix

// before - empty scheme from a bad substitution
<property>
  <name>dfs.namenode.edits.dir</name>
  <value>${eds.scheme}:///data/edits</value>
</property>

// after - explicit scheme
<property>
  <name>dfs.namenode.edits.dir</name>
  <value>file:///data/edits</value>
</property>
Defensive patterns

Strategy: validation

Validate before calling

// Config lint before first NN start
for (String key : Arrays.asList("dfs.namenode.name.dir", "dfs.namenode.edits.dir",
                                "dfs.namenode.shared.edits.dir")) {
  for (String loc : conf.getTrimmedStrings(key)) {
    if (loc == null || loc.isEmpty()) continue;
    URI u;
    try { u = URI.create(loc); } catch (IllegalArgumentException ex) { u = null; }
    boolean ok = u != null && u.getScheme() != null;
    if (!ok && !loc.startsWith("/")) {
      throw new IllegalArgumentException(key + " entry lacks a scheme and is not an absolute path: " + loc);
    }
  }
}

Type guard

static boolean hasScheme(String location) {
  if (location == null || location.isEmpty()) return false;
  try {
    return URI.create(location).getScheme() != null;
  } catch (IllegalArgumentException e) {
    return false;
  }
}

Try / catch

try {
  URI u = resolveStorageUri(dir);
  NNStorage.checkSchemeConsistency(u);
} catch (IOException e) {
  if (e.getMessage() != null && e.getMessage().startsWith("Undefined scheme for")) {
    throw new ConfigurationException("Storage URI needs an explicit scheme (file:///, hdfs://, qjm://): " + e.getMessage(), e);
  }
  throw e;
}

Prevention

When it happens

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

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

Related errors

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