{"record":{"id":"b68dcbf7ded9b1dc","repo":"apache/hadoop","slug":"cannot-find-matching-key-in-block","errorCode":null,"errorMessage":"Cannot find matching key in block.","messagePattern":"Cannot find matching key in block\\.","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/io/file/tfile/TFile.java","lineNumber":2040,"sourceCode":"          throws IOException {\n        int curBid = currentLocation.getBlockIndex();\n        long entryInBlock = reader.getBlockEntryCount(curBid);\n        if (curBid == endLocation.getBlockIndex()) {\n          entryInBlock = endLocation.getRecordIndex();\n        }\n\n        while (currentLocation.getRecordIndex() < entryInBlock) {\n          int cmp = compareCursorKeyTo(key);\n          if (cmp > 0) return false;\n          if (cmp == 0 && !greater) return true;\n          if (!valueBufferInputStream.isClosed()) {\n            valueBufferInputStream.close();\n          }\n          klen = -1;\n          currentLocation.incRecordIndex();\n        }\n\n        throw new RuntimeException(\"Cannot find matching key in block.\");\n      }\n    }\n\n    long getBlockEntryCount(int curBid) {\n      return tfileIndex.getEntry(curBid).entries();\n    }\n\n    BlockReader getBlockReader(int blockIndex) throws IOException {\n      return readerBCF.getDataBlock(blockIndex);\n    }\n  }\n\n  /**\n   * Data structure representing \"TFile.meta\" meta block.\n   */\n  static final class TFileMeta {\n    final static String BLOCK_NAME = \"TFile.meta\";\n    final Version version;","sourceCodeStart":2022,"sourceCodeEnd":2058,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/io/file/tfile/TFile.java#L2022-L2058","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Treat the file as corrupt: fsck it and regenerate from source; do not retry the seek on the same bytes.","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.","Catch the RuntimeException at the scan boundary and quarantine/skip the file in batch pipelines so one bad file doesn't kill the job."],"exampleFix":"// before\nTFile.Reader.Scanner s = reader.createScanner(beginKey, endKey);\n// after\ntry {\n  TFile.Reader.Scanner s = reader.createScanner(beginKey, endKey);\n} catch (RuntimeException e) {\n  // index/data disagreement: rebuild the file from source data\n  quarantine(path);\n}","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n  TFile.Reader.Scanner s = reader.createScanner(begin, end);\n  while (!s.atEnd()) { s.advance(); }\n} catch (RuntimeException e) {\n  // index/data invariant broken: quarantine file, continue batch\n}","preventionTips":["Pin one comparator implementation (same jar/version) on write and read paths.","Verify custom RawComparators are deterministic, reflexive and transitive with unit tests.","fsck and verify files before seek-heavy random access."],"tags":["tfile","hadoop-common","invariant","seek","data-corruption"],"backgroundTag":"corrupt-file-detected","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}