apache/cassandra · critical · StartupException

ERR_WRONG_DISK_STATE

ERR_WRONG_DISK_STATE

Error message

Has no permission to create directory %s

What it means

The checkDataDirectory startup check validates each configured data directory. If a directory does not exist and cannot be created because the Cassandra process lacks filesystem permission, a StartupException(ERR_WRONG_DISK_STATE) is thrown. Cassandra refuses to start because its commit log/data directories are essential for durability and storage.

Source

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

            if (configuration.isDisabled(name()))
                return;
            // check all directories(data, commitlog, saved cache) for existence and permission
            Iterable<String> dirs = Iterables.concat(Arrays.asList(DatabaseDescriptor.getAllDataFileLocations()),
                                                     Arrays.asList(DatabaseDescriptor.getCommitLogLocation(),
                                                                   DatabaseDescriptor.getSavedCachesLocation(),
                                                                   DatabaseDescriptor.getHintsDirectory().absolutePath()));
            for (String dataDir : dirs)
            {
                logger.debug("Checking directory {}", dataDir);
                File dir = new File(dataDir);

                // check that directories exist.
                if (!dir.exists())
                {
                    logger.warn("Directory {} doesn't exist", dataDir);
                    // if they don't, failing their creation, stop cassandra.
                    if (!dir.tryCreateDirectories())
                        throw new StartupException(StartupException.ERR_WRONG_DISK_STATE,
                                                   "Has no permission to create directory "+ dataDir);
                }

                // if directories exist verify their permissions
                if (!Directories.verifyFullPermissions(dir, dataDir))
                    throw new StartupException(StartupException.ERR_WRONG_DISK_STATE,
                                               "Insufficient permissions on directory " + dataDir);
            }
        }
    };

    public static final StartupCheck checkDirectIOSupport = new StartupCheck()
    {
        @Override
        public String name()
        {
            return "directio_support";
        }

View on GitHub (pinned to 88fd0f6a0e)

Solutions

  1. Create the directory manually and give ownership to the Cassandra user: 'sudo mkdir -p <dir> && sudo chown -R cassandra:cassandra <dir>'.
  2. Fix cassandra.yaml data_file_directories to point to a writable location for the user running Cassandra.
  3. If running in a container, mount the volume read-write and set correct UID/GID permissions.

Example fix

// before
data_file_directories: [/data/cassandra/data]
# /data is root-owned, cassandra user cannot create it
// after (shell)
// sudo mkdir -p /data/cassandra/data && sudo chown -R cassandra:cassandra /data/cassandra
Defensive patterns

Strategy: validation

Validate before calling

// pre-flight script before starting Cassandra
for dir in $DATA_DIRS; do
  if [ ! -d "$dir" ] && ! mkdir -p "$dir" 2>/dev/null; then
    echo "Cannot create $dir as $(whoami)"; exit 1
  fi
  test -w "$dir" || { echo "$dir not writable"; exit 1 }
done

Try / catch

try {
    startupChecks.execute(config);
} catch (StartupException e) {
    if (e.getErrorCode() == StartupException.ERR_WRONG_DISK_STATE)
        logger.error("Data directory problem: {} — fix ownership/permissions as the cassandra user", e.getMessage());
}

Prevention

When it happens

Trigger: checkDataDirectories.execute() iterates configured data_file_directories; dir.exists() is false and dir.tryCreateDirectories() returns false due to insufficient write permission on the parent, throwing the error with the offending dataDir path.

Common situations: cassandra.yaml points to a path under /root or /home owned by another user; directories were wiped or moved; Cassandra run as a different user than the directory owner; container volumes mounted read-only.

Understand the failure class

Background: mkdir permission denied (EACCES): failed to create directory errors explained — this error's family across 32 libraries.

Related errors

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