How to check HDFS cluster health

HDFS health checks need more than a daemon status check. A cluster can have running services while blocks are under-replicated, corrupt, missing, or stuck in safe mode.

Use hdfs dfsadmin -report for capacity and DataNode state, hdfs fsck for namespace and block health, and safe mode checks when writes or block reports are behaving unexpectedly.

Run checks from a Hadoop client with the same configuration and identity used by operators. A client pointed at the wrong nameservice can report a healthy but unrelated cluster.

1. Confirm the HDFS endpoint used by the client.

   $ hdfs getconf -confKey fs.defaultFS
   hdfs://cluster1

2. Check DataNode and capacity status.

   $ hdfs dfsadmin -report
   Configured Capacity: 322122547200 (300 GB)
   Present Capacity: 314572800000 (293 GB)
   Live datanodes (3):
   Dead datanodes (0):

3. Run an HDFS filesystem check from the root path.

   $ hdfs fsck /
   Status: HEALTHY
    Total size: 184320000 B
    Total dirs: 28
    Total files: 116
    Total blocks (validated): 42

4. Check safe mode state when writes fail.

   $ hdfs dfsadmin -safemode get
   Safe mode is OFF

5. List corrupt files only when the normal check reports a problem.

   $ hdfs fsck / -list-corruptfileblocks
   The filesystem under path '/' has 0 CORRUPT files

6. Record the health result with the NameNode timestamp.

   $ hdfs dfsadmin -report
   Name: worker01.example.net:9866
   Last contact: Wed Jun 17 03:50:11 UTC 2026
   Name: worker02.example.net:9866
   Last contact: Wed Jun 17 03:50:12 UTC 2026