apache/hadoop · error · IllegalArgumentException

Network Location path does not start with /: {}

Error message

Network Location path does not start with /: {}

What it means

NodeBase.normalize(path) requires every non-empty path to start with '/'; it then collapses duplicated slashes (SLASHES matcher) and strips one trailing '/'. Relative-looking locations such as 'default-rack' or 'rack1/ng1' throw IllegalArgumentException.

Source

Thrown at hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/net/NodeBase.java:168

  /** Normalize a path by stripping off any trailing {@link #PATH_SEPARATOR}
   * @param path path to normalize.
   * @return the normalised path
   * If <i>path</i>is null or empty {@link #ROOT} is returned
   * @throws IllegalArgumentException if the first character of a non empty path
   * is not {@link #PATH_SEPARATOR}
   */
  public static String normalize(String path) {
    if (path == null) {
      throw new IllegalArgumentException(
          "Network Location is null ");
    }

    if (path.length() == 0) {
      return ROOT;
    }

    if (path.charAt(0) != PATH_SEPARATOR) {
      throw new IllegalArgumentException(
                                         "Network Location path does not start with "
                                         +PATH_SEPARATOR_STR+ ": "+path);
    }

    // Remove duplicated slashes.
    path = SLASHES.matcher(path).replaceAll("/");
    
    int len = path.length();
    if (path.charAt(len-1) == PATH_SEPARATOR) {
      return path.substring(0, len-1);
    }
    return path;
  }
  
  /** @return this node's parent */
  @Override
  public Node getParent() { return parent; }
  

View on GitHub (pinned to 2add963021)

Solutions

1. Always use absolute locations starting with '/'
2. Run external location strings through NodeBase.normalize() (after the null check) at ingestion
3. Fix the mapping data/script to emit slash-prefixed paths

Example fix

// before
String loc = topologyScriptOutput(host); // "rack1"

// after
String loc = topologyScriptOutput(host);
if (loc != null && !loc.startsWith("/")) loc = "/" + loc;
loc = NodeBase.normalize(loc);

String loc = location;
if (loc != null && !loc.isEmpty() && loc.charAt(0) != '/') {
  loc = "/" + loc;
}
loc = NodeBase.normalize(loc);

static boolean hasLeadingSlash(String loc) {
  return loc != null && !loc.isEmpty() && loc.charAt(0) == '/';
}

When it happens

Trigger: new NodeBase(name, "default-rack"), NodeBase.normalize("rack1") in placement code, or topology scripts emitting rack names without the leading slash.

Common situations: Same misconfiguration family as NetworkTopology's normalizer: script output missing '/', hand-written StaticMapping values, locations copied from logs without the root slash.

Related errors

• Failed to add {}: You cannot have a rack and a non-rack node
• Unexpected data node {} at an illegal network location
• Network Locationpath doesn't start with /: {}
• Network location name contains /: {}
• Network Location is null

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