{"record":{"id":"3b6c90ac01c4145e","repo":"apache/hadoop","slug":"unexpected-blockucstate-is-but-not-under-co","errorCode":null,"errorMessage":"Unexpected BlockUCState: {} is {} but not UNDER_CONSTRUCTION","messagePattern":"Unexpected BlockUCState: (.+?) is (.+?) but not UNDER_CONSTRUCTION","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/namenode/FSNamesystem.java","lineNumber":6041,"sourceCode":"        file.getFileWithSnapshotFeature().isCurrentFileDeleted()) {\n      return true;\n    }\n    return false;\n  }\n\n  private INodeFile checkUCBlock(ExtendedBlock block,\n      String clientName) throws IOException {\n    assert hasWriteLock(RwLockMode.GLOBAL);\n    checkNameNodeSafeMode(\"Cannot get a new generation stamp and an \"\n        + \"access token for block \" + block);\n    \n    // check stored block state\n    BlockInfo storedBlock = getStoredBlock(ExtendedBlock.getLocalBlock(block));\n    if (storedBlock == null) {\n      throw new IOException(block + \" does not exist.\");\n    }\n    if (storedBlock.getBlockUCState() != BlockUCState.UNDER_CONSTRUCTION) {\n      throw new IOException(\"Unexpected BlockUCState: \" + block\n          + \" is \" + storedBlock.getBlockUCState()\n          + \" but not \" + BlockUCState.UNDER_CONSTRUCTION);\n    }\n    \n    // check file inode\n    final INodeFile file = getBlockCollection(storedBlock);\n    if (file == null || !file.isUnderConstruction() || isFileDeleted(file)) {\n      throw new IOException(\"The file \" + storedBlock + \n          \" belonged to does not exist or it is not under construction.\");\n    }\n    \n    // check lease\n    if (clientName == null\n        || !clientName.equals(file.getFileUnderConstructionFeature()\n            .getClientName())) {\n      throw new LeaseExpiredException(\"Lease mismatch: \" + block + \n          \" is accessed by a non lease holder \" + clientName); \n    }","sourceCodeStart":6023,"sourceCodeEnd":6059,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/namenode/FSNamesystem.java#L6023-L6059","documentation":"checkUCBlock found the block but its BlockUCState is not UNDER_CONSTRUCTION (already COMMITTED or COMPLETE), so a new generation stamp cannot be minted for it. The block has moved past the recoverable state the caller assumes.","triggerScenarios":"Pipeline recovery racing block commit or file completion: the block got committed by a first (unacknowledged) attempt, or lease recovery elsewhere advanced the block state.","commonSituations":"Timeout-and-retry of updateBlock without checking state; two clients concurrently recovering the same file.","solutions":["Refresh block state (getBlockLocations) and if the file is closed, accept the earlier recovery as final","If the file is still open, re-run recoverLease and continue from the new block state","Serialize recovery attempts per file in client code"],"exampleFix":null,"handlingStrategy":"retry","validationCode":"LocatedBlock last = dfs.getClient().getLastLocatedBlock(path);\nif (last != null && last.isBlockUnderConstruction()) { /* safe to request new GS */ }","typeGuard":null,"tryCatchPattern":"try {\n  nextGenerationStamp(block, clientName);\n} catch (IOException e) {\n  if (e.getMessage().contains(\"Unexpected BlockUCState\")) {\n    // state advanced (committed/completed): verify file state and move on\n    if (dfs.isFileClosed(path)) { return; }\n    dfs.recoverLease(path); // else restart recovery from current state\n  } else { throw e; }\n}","preventionTips":["Check the block's UC state from LocatedBlock before requesting a new GS","Never blindly retry recovery; first confirm what already happened"],"tags":["hdfs","namenode","block-state","pipeline-recovery","state-machine"],"backgroundTag":"invalid-state-transition","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}