apache/cassandra · error · ConfigurationException

Unable check disk space in '%s'. Perhaps the Cassandra user

Error message

Unable check disk space in '%s'. Perhaps the Cassandra user does not have the necessary permissions

What it means

tryGetSpace asks the filesystem for a directory's space via PathUtils.tryGetSpace using a FileStore query; if the query throws IOException, the lambda converts it into this ConfigurationException. Cassandra needs disk-usage figures at startup to enforce space thresholds, so an unreadable data/commitlog directory aborts initialization.

Source

Thrown at src/java/org/apache/cassandra/config/DatabaseDescriptor.java:2038

    /**
     * Computes the sum of the 2 specified positive values returning {@code Long.MAX_VALUE} if the sum overflow.
     *
     * @param left  the left operand
     * @param right the right operand
     * @return the sum of the 2 specified positive values of {@code Long.MAX_VALUE} if the sum overflow.
     */
    private static long saturatedSum(long left, long right)
    {
        assert left >= 0 && right >= 0;
        long sum = left + right;
        return sum < 0 ? Long.MAX_VALUE : sum;
    }

    private static long tryGetSpace(String dir, PathUtils.IOToLongFunction<FileStore> getSpace)
    {
        return PathUtils.tryGetSpace(new File(dir).toPath(), getSpace, e -> {
            throw new ConfigurationException("Unable check disk space in '" + dir + "'. Perhaps the Cassandra user does not have the necessary permissions");
        });
    }

    public static IEndpointSnitch createEndpointSnitch(String snitchClassName) throws ConfigurationException
    {
        if (!snitchClassName.contains("."))
            snitchClassName = "org.apache.cassandra.locator." + snitchClassName;
        IEndpointSnitch snitch = FBUtilities.construct(snitchClassName, "snitch", IEndpointSnitch.class);
        return snitch;
    }

    public static NodeProximity createProximityImpl(String className) throws ConfigurationException
    {
        if (!className.contains("."))
            className = "org.apache.cassandra.locator." + className;
        NodeProximity sorter = FBUtilities.construct(className, "node proximity measurement", NodeProximity.class);
        return sorter;
    }

View on GitHub (pinned to 88fd0f6a0e)

Solutions

  1. Fix filesystem permissions so the Cassandra user can stat/read the directory (chown/chmod)
  2. Verify the volume is actually mounted at the configured path before starting Cassandra
  3. Correct the directory path in cassandra.yaml to an existing, accessible location

Example fix

// before
chown root:root /var/lib/cassandra
// after
chown -R cassandra:cassandra /var/lib/cassandra
Defensive patterns

Strategy: try-catch

Validate before calling

for (String dir : allConfiguredDirectories)
    if (!Files.isReadable(Paths.get(dir)))
        throw new IllegalStateException("Cassandra user cannot read " + dir);

Try / catch

try { DatabaseDescriptor.daemonInitialization(); }
catch (ConfigurationException e) {
    if (e.getMessage().startsWith("Unable check disk space"))
        repairMountAndPermissions();
}

Prevention

When it happens

Trigger: Calling a DatabaseDescriptor space check (e.g. getTotalFilespace / disk-usage validation over data_file_directories or commitlog_directory) where the FileStore query on the directory path fails due to permissions, an unmounted volume, or an IO error.

Common situations: cassandra.yaml points data_file_directories/commitlog_directory at a path the cassandra OS user cannot read; NFS/automount not mounted at boot; directory removed after config parse but before the space check; containers with restricted volume permissions.

Understand the failure class

Background: Permission denied / not authorized / 403 Forbidden: access-control rejections when the caller lacks the required role, grant, or ownership — this error's family across 18 libraries.

Related errors

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