What causes "The filePath should not be null!" in apache/hadoop?

Look at the caller of deleteMappedFile in the stack trace and fix it to pass the captured path - assign the path before work begins and delete in a finally block.

apache/hadoop · error · IOException

The filePath should not be null!

Error message

The filePath should not be null!

What it means

FsDatasetUtil.deleteMappedFile cleans up a memory-mapped temporary file used while computing block checksums. The IOException is a plain null guard: the caller passed a null path, meaning internal state about the mapped file was lost before cleanup. It signals a programming error inside the DataNode or test code, not a configuration problem.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/datanode/fsdataset/impl/FsDatasetUtil.java:228

    ReplicaInfo wrapper = new FinalizedReplica(0, 0, 0, null, null) {
      @Override
      public URI getMetadataURI() {
        return srcMeta.toURI();
      }

      @Override
      public InputStream getDataInputStream(long seekOffset)
          throws IOException {
        return Files.newInputStream(blockFile.toPath());
      }
    };

    FsDatasetImpl.computeChecksum(wrapper, dstMeta, smallBufferSize, conf);
  }

  public static void deleteMappedFile(String filePath) throws IOException {
    if (filePath == null) {
      throw new IOException("The filePath should not be null!");
    }
    boolean result = Files.deleteIfExists(Paths.get(filePath));
    if (!result) {
      throw new IOException(
          "Failed to delete the mapped file: " + filePath);
    }
  }
}

View on GitHub (pinned to 2add963021)

Solutions

Look at the caller of deleteMappedFile in the stack trace and fix it to pass the captured path - assign the path before work begins and delete in a finally block.
No block data is at risk: the mapped file holds only intermediate checksum data; clean leftover temp files if any.
If it is stock unmodified Hadoop code, report it with the stack trace.

Example fix

// before
deleteMappedFile(null); // path lost when computation failed early

// after
String mappedPath = null;
try {
  mappedPath = createMappedFile();
  compute(mappedPath);
} finally {
  if (mappedPath != null) {
    FsDatasetUtil.deleteMappedFile(mappedPath);
  }
}

Defensive patterns

Strategy: validation

Validate before calling

if (filePath == null) {
  // nothing to clean: skip the call
  return;
}
FsDatasetUtil.deleteMappedFile(filePath);

Try / catch

try {
  FsDatasetUtil.deleteMappedFile(path);
} catch (IOException e) {
  // internal caller bug: log with the stack and continue cleanup
}

Prevention

Assign the mapped-file path before any work that can fail; delete in finally.
Never call deleteMappedFile with an untracked path variable.
Write tests that exercise checksum-computation failure paths to catch null-path cleanup bugs.

When it happens

Trigger: Internal caller invokes deleteMappedFile after checksum computation failed before the path was assigned; test code passes null; a race clears the mapped-file holder early.

Common situations: Only in custom builds, patched DataNodes, or unit tests exercising checksum computation.

Related errors

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