apache/hadoop · error · IllegalArgumentException

Network Locationpath doesn't start with /: {}

Error message

Network Locationpath doesn't start with /: {}

What it means

NetworkTopology.normalizeNetworkLocationPath validates location strings used inside the topology: null or empty maps to ROOT, but any non-empty path must start with '/' (PATH_SEPARATOR), otherwise IllegalArgumentException. It also strips one trailing '/'.

Source

Thrown at hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/net/NetworkTopology.java:860

      }
    }
    return weight;
  }

  /** 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}
   */
  private static String normalizeNetworkLocationPath(String path) {
    if (path == null || path.length() == 0) {
      return ROOT;
    }

    if (path.charAt(0) != PATH_SEPARATOR) {
      throw new IllegalArgumentException("Network Location"
          + "path doesn't start with " +PATH_SEPARATOR+ ": "+path);
    }

    int len = path.length();
    if (path.charAt(len-1) == PATH_SEPARATOR) {
      return path.substring(0, len-1);
    }
    return path;
  }

  /**
   * Sort nodes array by network distance to <i>reader</i>.
   * <p>
   * In a three-level topology, a node can be either local, on the same rack,
   * or on a different rack from the reader. Sorting the nodes based on network
   * distance from the reader reduces network traffic and improves
   * performance.
   * <p>

View on GitHub (pinned to 2add963021)

Solutions

1. Prefix every location with '/' — '/default-rack', '/dc1/rack1'
2. Normalize external input with NodeBase.normalize() before handing it to NetworkTopology
3. Fix the topology script to print absolute slash-prefixed paths

Example fix

// before
node.setNetworkLocation("default-rack");

// after
node.setNetworkLocation("/default-rack");

String loc = node.getNetworkLocation();
if (loc == null || loc.isEmpty()) loc = "/default-rack";
else if (loc.charAt(0) != '/') loc = "/" + loc;
node.setNetworkLocation(loc);

static boolean isValidLocationPath(String loc) {
  return loc == null || loc.isEmpty() || loc.charAt(0) == '/';
}

When it happens

Trigger: Any internal path-normalization call where the location string is like "default-rack" or "rack1/nodegroup" — missing the leading slash. Reached via NetworkTopology's network-location handling (e.g. setNetworkLocation paths used by add/getDatanodesInRack).

Common situations: Topology scripts emitting bare rack names without a leading '/'; hand-built Node objects in tests with unnormalized locations; config values copied without the leading slash.

Related errors

• Network location name contains /: {}
• Not allow to add an inner node: {}
• Not allow to remove an inner node: {}
• Network Location path does not start with /: {}
• getXAttrs on path `{}' is not within a mount point

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