apache/cassandra · warning

IO exception while reading file {}.

Error message

IO exception while reading file {}.

What it means

In DiskCheck/CheckReadAhead machinery, getBlockDevices walks each configured data directory to resolve its backing block device by reading sysfs paths. If an IOException occurs while reading the directory/files, it logs 'IO exception while reading file {dataDirectory}.' with the exception, skips that directory, and continues. The startup check degrades gracefully rather than failing startup.

Source

Thrown at src/java/org/apache/cassandra/service/StartupChecks.java:726

        private Map<String, String> getBlockDevices(String[] dataDirectories) {
            Map<String, String> blockDevices = new HashMap<String, String>();

            for (String dataDirectory : dataDirectories)
            {
                try
                {
                    Path p = File.getPath(dataDirectory);
                    FileStore fs = Files.getFileStore(p);

                    String blockDirectory = fs.name();
                    if(StringUtils.isNotEmpty(blockDirectory))
                    {
                        blockDevices.put(blockDirectory, dataDirectory);
                    }
                }
                catch (IOException e)
                {
                    logger.warn("IO exception while reading file {}.", dataDirectory, e);
                }
            }
            return blockDevices;
        }

        @Override
        public void execute(StartupChecksConfiguration configuration)
        {
            if (configuration.isDisabled(name()) || !FBUtilities.isLinux)
                return;

            String[] dataDirectories = DatabaseDescriptor.getRawConfig().data_file_directories;
            Map<String, String> blockDevices = getBlockDevices(dataDirectories);

            for (Map.Entry<String, String> entry: blockDevices.entrySet())
            {
                String blockDeviceDirectory = entry.getKey();
                String dataDirectory = entry.getValue();

View on GitHub (pinned to 88fd0f6a0e)

Solutions

  1. Inspect the logged exception for the actual failing path and fix permissions (chown cassandra:cassandra on the data directory).
  2. Mount /sys read-write or at least readable into containers running Cassandra.
  3. Verify data_file_directories in cassandra.yaml point to existing, readable paths.
  4. If the warning is expected for your storage topology, treat it as informational; read-ahead checks are skipped for that device.

Example fix

// before
data_file_directories: [/mnt/missing-disk/data]
// after
data_file_directories: [/var/lib/cassandra/data]  # existing, readable path
Defensive patterns

Strategy: try-catch

Validate before calling

for (String dir : dataDirs) {
    File f = new File(dir);
    if (!f.canRead()) System.out.println("Unreadable data directory: " + dir);
}
if (!new File("/sys/block").canRead()) System.out.println("/sys/block not accessible; device checks will be skipped");

Try / catch

try {
    // device/directory probing
} catch (IOException e) {
    logger.warn("IO exception while reading file {}.", dataDirectory, e);
    // fall back: skip read-ahead check for this directory
}

Prevention

When it happens

Trigger: IOException while listing/reading the sysfs block-device path or data directory during getBlockDevices (e.g. /sys entries missing, unreadable /proc/self/mountinfo, I/O error on the data directory).

Common situations: Containers without /sys/block mounted, unusual storage layouts (LVM/loop devices), permission-restricted data directories, NFS or ephemeral mounts where sysfs resolution fails.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

AI-assisted analysis of apache/cassandra@88fd0f6a0e (2026-09-10). Data as JSON: /api/errors/ec47dc5ad649def3. Report an issue: GitHub.