apache/hadoop · error · DiskBalancerException

UNKNOWN_KEY

UNKNOWN_KEY

Error message

Unknown key

What it means

getDiskBalancerSetting is a small key/value settings RPC that recognizes exactly two keys: DiskBalancerConstants.DISKBALANCER_VOLUME_NAME (volume list) and DISKBALANCER_BANDWIDTH (current bandwidth). Anything else falls through to default, logs the offending key, and raises DiskBalancerException Result.UNKNOWN_KEY.

Source

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

   * example : DiskBalancer bandwidth.
   *
   * @param key - String that represents the run time key value.
   * @return value of the key as a string.
   * @throws IOException - Throws if there is no such key
   */
  @Override
  public String getDiskBalancerSetting(String key) throws IOException {
    checkSuperuserPrivilege();
    Preconditions.checkNotNull(key);
    switch (key) {
    case DiskBalancerConstants.DISKBALANCER_VOLUME_NAME:
      return getDiskBalancer().getVolumeNames();
    case DiskBalancerConstants.DISKBALANCER_BANDWIDTH :
      return Long.toString(getDiskBalancer().getBandwidth());
    default:
      LOG.error("Disk Balancer - Unknown key in get balancer setting. Key: {}",
          key);
      throw new DiskBalancerException("Unknown key",
          DiskBalancerException.Result.UNKNOWN_KEY);
    }
  }

  @VisibleForTesting
  void setBlockScanner(BlockScanner blockScanner) {
    this.blockScanner = blockScanner;
  }

  @Override // DataNodeMXBean
  public String getSendPacketDownstreamAvgInfo() {
    return dnConf.peerStatsEnabled && peerMetrics != null ?
        peerMetrics.dumpSendPacketDownstreamAvgInfoAsJson() : null;
  }

  @Override // DataNodeMXBean
  public String getSlowDisks() {
    if (!dnConf.diskStatsEnabled || diskMetrics == null) {

View on GitHub (pinned to 2add963021)

Solutions

1. Use the constants from org.apache.hadoop.hdfs.server.datanode.diskbalancer.DiskBalancerConstants instead of string literals
2. Trim and normalize the key before sending it
3. Check the DN log line 'Disk Balancer - Unknown key ... Key: X' to see the exact string that arrived at the server

Example fix

// before
String bw = protocol.getDiskBalancerSetting("bandwidth "); // typo + whitespace -> UNKNOWN_KEY

// after
String bw = protocol.getDiskBalancerSetting(
    DiskBalancerConstants.DISKBALANCER_BANDWIDTH.trim());

Set<String> allowed = new HashSet<>(Arrays.asList(
    DiskBalancerConstants.DISKBALANCER_VOLUME_NAME,
    DiskBalancerConstants.DISKBALANCER_BANDWIDTH));
if (!allowed.contains(key)) {
  throw new IllegalArgumentException("Unsupported disk balancer setting: " + key);
}
String value = protocol.getDiskBalancerSetting(key);

catch (DiskBalancerException e) {
  if (e.getResult() == DiskBalancerException.Result.UNKNOWN_KEY) {
    // surface which key was rejected; correct and retry
  } else { throw e; }
}

When it happens

Trigger: Calling ClientDatanodeProtocol.getDiskBalancerSetting with any key other than the two supported constants - misspelled key, wrong case, stray whitespace, or an invented setting name.

Common situations: Tooling built with hardcoded strings instead of DiskBalancerConstants; clients written against a different Hadoop version; config interpolation inserting whitespace into the key.

Related errors

• DiskBalancer is not initialized
• Not a valid Boolean value for {property} in reconfSlowPeerPa
• Not a valid Boolean value for {property}
• No directory is specified.
• Invalid value configured for dfs.datanode.failed.volumes.tol

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