apache/hadoop · error · IllegalArgumentException

Capacity ratio{} is not between 0 to 1: {}

Error message

Capacity ratio{} is not between 0 to 1: {}

What it means

StorageLocation.parseCapacityRatio() parses dfs.datanode.same.disk.tiering.capacity.ratio.percentage, a comma list of '[ratio]/path' entries (regex ^\[([0-9.]*)\](.+)$) that assigns each volume a fraction of its disk for same-disk tiering. After Double.parseDouble, a ratio outside [0,1] (negative or greater than 1) throws IllegalArgumentException listing the bad ratio and entry.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/datanode/StorageLocation.java:182

   * @throws SecurityException when format is incorrect or ratio is not
   *         between 0 - 1.
   */
  public static Map<URI, Double> parseCapacityRatio(String capacityRatioConf)
      throws SecurityException {
    Map<URI, Double> result = new HashMap<>();
    capacityRatioConf = capacityRatioConf.replaceAll("\\s", "");
    if (capacityRatioConf.isEmpty()) {
      return result;
    }
    String[] capacityRatios = capacityRatioConf.split(",");
    for (String ratio : capacityRatios) {
      Matcher matcher = CAPACITY_RATIO_REGEX.matcher(ratio);
      if (matcher.matches()) {
        String capacityString = matcher.group(1).trim();
        String location = matcher.group(2).trim();
        double capacityRatio = Double.parseDouble(capacityString);
        if (capacityRatio > 1 || capacityRatio < 0) {
          throw new IllegalArgumentException("Capacity ratio" + capacityRatio
              + " is not between 0 to 1: " + ratio);
        }
        result.put(new Path(location).toUri(), capacityRatio);
      } else {
        throw new IllegalArgumentException(
            "Capacity ratio config is not with correct format: "
                + capacityRatioConf
        );
      }
    }
    return result;
  }

  @Override
  public String toString() {
    return "[" + storageType + "]" + baseURI.normalize();
  }

View on GitHub (pinned to 2add963021)

Solutions

1. Rewrite every ratio as a fraction between 0 and 1 inclusive, e.g. [0.5]/disk1/archive
2. If you intended percentages, divide by 100: 30% -> [0.3]
3. Restart the DataNode and confirm parse succeeds (no startup abort)

Example fix

# before (hdfs-site.xml)
<property>
  <name>dfs.datanode.same.disk.tiering.capacity.ratio.percentage</name>
  <value>[50]/disk1/archive,[0.3]/disk2/archive</value>
</property>

# after
<property>
  <name>dfs.datanode.same.disk.tiering.capacity.ratio.percentage</name>
  <value>[0.5]/disk1/archive,[0.3]/disk2/archive</value>
</property>

import java.util.regex.*;
static final Pattern P = Pattern.compile("^\\[([0-9.]*)\\](.+)$");
void checkCapacityRatios(String conf) {
  for (String t : conf.replaceAll("\\s", "").split(",")) {
    Matcher m = P.matcher(t);
    if (!m.matches()) throw new IllegalArgumentException("Bad format: " + t);
    double d = Double.parseDouble(m.group(1));
    if (d < 0 || d > 1) throw new IllegalArgumentException("Ratio out of [0,1]: " + t);
  }
}

When it happens

Trigger: Configuring e.g. [1.2]/disk1 or [-0.1]/disk1 in dfs.datanode.same.disk.tiering.capacity.ratio.percentage; also values like [0.5.] that parse to something odd, or percentages written as [50] instead of the fractional [0.5].

Common situations: Same-disk-tiering setups (mixing ARCHIVE on DISK mounts, HDFS-15418 era feature) where the admin wrote a percentage (50) instead of a fraction (0.5), or fractions that individually pass but were intended to sum differently; typos like 2.0 for 0.2.

Related errors

• Capacity ratio config is not with correct format: {}
• URI: {} is not in the expected format
• Xceiver count {} exceeds the limit of concurrent xceivers: {
• Cannot create directory {rootPath}
• Incompatible node types: storageType={storageType} but Stora

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