apache/hadoop · error · IOException

Fail to get checksum, since file {} is under construction.

Error message

Fail to get checksum, since file {} is under construction.

What it means

getFileChecksum requires finalized blocks with stable CRCs. If the file's last block is still under construction — some writer holds the file open for create/append — getBlockLocations reports isUnderConstruction and the client aborts with IOException('Fail to get checksum, since file ... is under construction.') rather than returning a partial checksum.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/DFSClient.java:1965

   * @return The checksum
   * @see DistributedFileSystem#getFileChecksum(Path)
   */
  public MD5MD5CRC32FileChecksum getFileChecksum(String src, long length)
      throws IOException {
    return (MD5MD5CRC32FileChecksum) getFileChecksumInternal(
        src, length, ChecksumCombineMode.MD5MD5CRC);
  }

  protected LocatedBlocks getBlockLocations(String src,
                                            long length) throws IOException {
    //get block locations for the file range
    LocatedBlocks blockLocations = callGetBlockLocations(namenode,
        src, 0, length);
    if (null == blockLocations) {
      throw new FileNotFoundException("File does not exist: " + src);
    }
    if (blockLocations.isUnderConstruction()) {
      throw new IOException("Fail to get checksum, since file " + src
          + " is under construction.");
    }

    return blockLocations;
  }

  protected IOStreamPair connectToDN(DatanodeInfo dn, int timeout,
                                     Token<BlockTokenIdentifier> blockToken)
      throws IOException {
    return DFSUtilClient.connectToDN(dn, timeout, conf, saslClient,
        socketFactory, getConf().isConnectToDnViaHostname(), this, blockToken);
  }

  /**
   * Infer the checksum type for a replica by sending an OP_READ_BLOCK
   * for the first byte of that replica. This is used for compatibility
   * with older HDFS versions which did not include the checksum type in
   * OpBlockChecksumResponseProto.

View on GitHub (pinned to 2add963021)

Solutions

Fix the writer: guarantee close via try-with-resources on every FSDataOutputStream so no file is left under construction.
Sequence the pipeline: writers emit a completion marker (_SUCCESS or final atomic rename) after close; verifiers only run past the marker.
If a writer may legitimately still be active, bounded-retry the checksum until the file is no longer under construction.
If the lease is orphaned (writer died), wait for lease recovery or trigger it, then retry.

Example fix

// before
FileChecksum cs = fs.getFileChecksum(path);
// IOException: Fail to get checksum, since file <path> is under construction.

// after: bounded wait for the writer to finish
FileChecksum cs = null;
for (int i = 0; i < 30; i++) {
  try {
    cs = fs.getFileChecksum(path);
    break;
  } catch (IOException e) {
    if (!e.getMessage().contains("under construction")) { throw e; }
    Thread.sleep(1000);
  }
}

Defensive patterns

Strategy: retry

Validate before calling

// @InterfaceAudience.Private but public: check UC state before checksumming
HdfsFileStatus st = ((DistributedFileSystem) fs).getClient().getFileInfo(path);
if (st != null && st.isUnderConstruction()) {
  // a writer still holds the file: wait for close before getFileChecksum
}

Try / catch

catch (IOException e) {
  if (e.getMessage().contains("under construction")) {
    // bounded wait/retry until the writer closes, then retry the checksum
  } else { throw e; }
}

Prevention

Use try-with-resources for every FSDataOutputStream; audit exception paths for skipped close().
Gate verification on completion markers (_SUCCESS / final rename) emitted after writers close.
For orphaned leases, trigger or await lease recovery before verifying.

When it happens

Trigger: Checksumming a file that the same process or another client is still writing: a leaked FSDataOutputStream (an exception path skipped close), verification steps running before the writer's committer closed files, or append-mode log files audited while open.

Common situations: Output verification racing job commit; long-lived append writers (log aggregation) checked by auditors; close() failures swallowed earlier leaving the lease and UC state behind.

Related errors

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