apache/hadoop · error · RuntimeException

Cannot find matching key in block.

Error message

Cannot find matching key in block.

What it means

RuntimeException at the end of Scanner.seekToKeyValueInBlock(). After the block index says the seek target should be inside the current block, the method walks entryInBlock records comparing keys; a cmp > 0 means 'past it, not found' and cmp == 0 means found. If the record index reaches entryInBlock without either exit firing, the data block's contents disagree with the block index entry count — an internal invariant break, almost always corruption or an inconsistent comparator.

Source

Thrown at hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/io/file/tfile/TFile.java:2040

          throws IOException {
        int curBid = currentLocation.getBlockIndex();
        long entryInBlock = reader.getBlockEntryCount(curBid);
        if (curBid == endLocation.getBlockIndex()) {
          entryInBlock = endLocation.getRecordIndex();
        }

        while (currentLocation.getRecordIndex() < entryInBlock) {
          int cmp = compareCursorKeyTo(key);
          if (cmp > 0) return false;
          if (cmp == 0 && !greater) return true;
          if (!valueBufferInputStream.isClosed()) {
            valueBufferInputStream.close();
          }
          klen = -1;
          currentLocation.incRecordIndex();
        }

        throw new RuntimeException("Cannot find matching key in block.");
      }
    }

    long getBlockEntryCount(int curBid) {
      return tfileIndex.getEntry(curBid).entries();
    }

    BlockReader getBlockReader(int blockIndex) throws IOException {
      return readerBCF.getDataBlock(blockIndex);
    }
  }

  /**
   * Data structure representing "TFile.meta" meta block.
   */
  static final class TFileMeta {
    final static String BLOCK_NAME = "TFile.meta";
    final Version version;

View on GitHub (pinned to 2add963021)

Solutions

1. Treat the file as corrupt: fsck it and regenerate from source; do not retry the seek on the same bytes.
2. If a jclass comparator is in play, verify the exact same comparator implementation (same version, deterministic, transitive) is on the read-side classpath as wrote the file.
3. Catch the RuntimeException at the scan boundary and quarantine/skip the file in batch pipelines so one bad file doesn't kill the job.

Example fix

// before
TFile.Reader.Scanner s = reader.createScanner(beginKey, endKey);
// after
try {
  TFile.Reader.Scanner s = reader.createScanner(beginKey, endKey);
} catch (RuntimeException e) {
  // index/data disagreement: rebuild the file from source data
  quarantine(path);
}

try {
  TFile.Reader.Scanner s = reader.createScanner(begin, end);
  while (!s.atEnd()) { s.advance(); }
} catch (RuntimeException e) {
  // index/data invariant broken: quarantine file, continue batch
}

When it happens

Trigger: seek()/createScanner(key, key) landing on a block whose recorded entry count does not match the decodable records, or a custom jclass comparator whose ordering differs between the writer that built the index and the reader doing the seek (not a stable total order).

Common situations: Corrupt block index after truncated writes, comparator class changed semantics between write and read (e.g. locale-dependent or versioned compare logic), or reading files whose comparator class on the classpath is not the one used at write time.

Related errors

• Key length out of range: {klen}
• First key entry size out of range: {size}
• First key length out of range: {firstKeyLength}
• Index entry size out of range: {size}
• Internal error

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