What causes ""concat: target file " + target + " is under construction"" in apache/hadoop?

Ensure the target's writer is closed (try-with-resources) before concat is invoked.

apache/hadoop · error · HadoopIllegalArgumentException

"concat: target file " + target + " is under construction"

Error message

"concat: target file " + target + " is under construction"

What it means

Concat requires the target file to be finalized: verifyTargetFile checks INodeFile.isUnderConstruction() and throws HadoopIllegalArgumentException if a writer still holds the file open. Concat works by unlinking source inodes and splicing their block lists onto the target's, which is only meaningful once the target's own block list is stable. A file stays 'under construction' until the writer closes it or its lease is recovered.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/namenode/FSDirConcatOp.java:109

      if (FSDirectory.isReservedRawName(srcPath)
          || FSDirectory.isReservedInodesName(srcPath)) {
        throw new IOException("Concat operation doesn't support "
            + FSDirectory.DOT_RESERVED_STRING + " relative path : " + srcPath);
      }
    }
  }

  private static void verifyTargetFile(FSDirectory fsd, final String target,
      final INodesInPath targetIIP) throws IOException {
    // check the target
    if (FSDirEncryptionZoneOp.getEZForPath(fsd, targetIIP) != null) {
      throw new HadoopIllegalArgumentException(
          "concat can not be called for files in an encryption zone.");
    }
    final INodeFile targetINode = INodeFile.valueOf(targetIIP.getLastINode(),
        target);
    if(targetINode.isUnderConstruction()) {
      throw new HadoopIllegalArgumentException("concat: target file "
          + target + " is under construction");
    }
  }

  private static INodeFile[] verifySrcFiles(FSDirectory fsd, String[] srcs,
      INodesInPath targetIIP, FSPermissionChecker pc) throws IOException {
    // to make sure no two files are the same
    Set<INodeFile> si = new LinkedHashSet<>();
    final INodeFile targetINode = targetIIP.getLastINode().asFile();
    final INodeDirectory targetParent = targetINode.getParent();
    // now check the srcs
    for(String src : srcs) {
      final INodesInPath iip = fsd.resolvePath(pc, src, DirOp.WRITE);
      // permission check for srcs
      if (pc != null && fsd.isPermissionEnabled()) {
        fsd.checkPathAccess(pc, iip, FsAction.READ); // read the file
        fsd.checkParentAccess(pc, iip, FsAction.WRITE); // for delete
      }

View on GitHub (pinned to 2add963021)

Solutions

Ensure the target's writer is closed (try-with-resources) before concat is invoked.
For a crashed writer, force lease recovery first: DistributedFileSystem.recoverLease(target), wait for recovery to finalize, then concat.
Check for an active lease before scheduling compaction and defer the file to the next compaction cycle.

Example fix

// before
FSDataOutputStream out = fs.create(target);
// ... writing ...
fs.concat(target, srcs); // target still under construction

// after
try (FSDataOutputStream out = fs.create(target)) {
  // ... writing ...
} // target finalized on close
fs.concat(target, srcs);

Defensive patterns

Strategy: validation

Validate before calling

DistributedFileSystem dfs = (DistributedFileSystem) fs;
if (!dfs.recoverLease(target)) {
  // file is still open for a live writer: defer this target to the next cycle
  scheduleForRetry(target);
  return;
}

Try / catch

catch (HadoopIllegalArgumentException e) {
  if (e.getMessage() != null && e.getMessage().contains("under construction")) {
    fs.recoverLease(target); // finalize crashed writers, then retry once
    fs.concat(target, srcs);
  } else { throw e; }
}

Prevention

Always close writers with try-with-resources before the file becomes a concat target.
Do not include the currently-open output file of a rolling writer in the concat list.
Run recoverLease defensively on any file whose writer process may have crashed before compaction.

When it happens

Trigger: Calling concat on a target that an FSDataOutputStream is still writing to; a target whose writer crashed without closing (lease still held within the soft-limit window); calling concat immediately after create() but before close().

Common situations: Streaming ingest jobs that periodically 'roll' files and concat predecessors while the current file is still open; jobs killed mid-write leaving orphaned open files that a cleanup/compaction job later tries to use as concat targets.

Related errors

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