apache/cassandra · critical · ConfigurationException

is missing and cassandra.storagedir system property is not

Error message

 is missing and cassandra.storagedir system property is not set

What it means

DatabaseDescriptor.storagedir() resolves the storage directory from the cassandra.storagedir system property (STORAGE_DIR). When it is not set, every storagedirFor() caller (commitlog_directory, saved_caches_directory, data_file_directories, etc.) throws this ConfigurationException. The message is prefixed with the specific directory type that is missing.

Source

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

            StartupChecks startupChecks = new StartupChecks().withDefaultTests().withTest(new FileSystemOwnershipCheck()).withServiceLoaderTests();
            startupChecksConfiguration = new StartupChecksConfiguration(startupChecks, conf.startup_checks);
        }
        catch (Throwable t)
        {
            throw new ConfigurationException("Invalid configuration of startup_checks: " + t.getMessage());
        }
    }

    private static String storagedirFor(String type)
    {
        return storagedir(type + "_directory") + File.pathSeparator() + type;
    }

    private static String storagedir(String errMsgType)
    {
        String storagedir = STORAGE_DIR.getString();
        if (storagedir == null)
            throw new ConfigurationException(errMsgType + " is missing and " + STORAGE_DIR.getKey() + " system property is not set", false);
        return storagedir;
    }

    static int calculateDefaultSpaceInMiB(String type, String path, String setting, int preferredSizeInMiB, long totalSpaceInBytes, long totalSpaceNumerator, long totalSpaceDenominator)
    {
        final long totalSizeInMiB = totalSpaceInBytes / ONE_MIB;
        final int minSizeInMiB = Ints.saturatedCast(totalSpaceNumerator * totalSizeInMiB / totalSpaceDenominator);

        if (minSizeInMiB < preferredSizeInMiB)
        {
            logger.warn("Small {} volume detected at '{}'; setting {} to {}.  You can override this in cassandra.yaml",
                        type, path, setting, minSizeInMiB);
            return minSizeInMiB;
        }
        else
        {
            return preferredSizeInMiB;
        }

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Start Cassandra with -Dcassandra.storagedir=/var/lib/cassandra (or set CASSANDRA_OPTS in cassandra-env.sh).
2. Alternatively set the explicit directory settings in cassandra.yaml (data_file_directories, commitlog_directory, saved_caches_directory, hints_directory).
3. Ensure directories exist and are writable by the cassandra user.

Example fix

// before
cassandra-env.sh: JVM_OPTS="$JVM_OPTS"
// after
cassandra-env.sh: JVM_OPTS="$JVM_OPTS -Dcassandra.storagedir=/var/lib/cassandra"

// fail fast in launcher scripts before starting the JVM
if [ -z "$CASSANDRA_STORAGEDIR" ] && ! grep -qE '(data_file_directories|commitlog_directory):' conf/cassandra.yaml; then
  echo "Set -Dcassandra.storagedir or directory settings in cassandra.yaml" >&2; exit 1;
fi

catch (ConfigurationException e) { logger.error("Storage directory not configured: {}", e.getMessage()); System.exit(2); }

When it happens

Trigger: Neither the relevant *_directory setting in cassandra.yaml nor the cassandra.storagedir system property is set, and code calls storagedirFor("commitlog") (or data/saved_caches/hints) to derive a path.

Common situations: Running Cassandra with a minimal cassandra.yaml that omits directories while expecting the storagedir property to be set; launching via a script that does not pass -Dcassandra.storagedir; Docker/containers where the entrypoint forgets to export the system property.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• Unable to determine block size for commit log directory: {}
• Load CIDR groups cache operation not supported by %s
• Unsupported parameter '%s' for %s, supported parameters are
• JAAS login configuration missing for JMX authenticator setup
• repair_session_max_tree_depth should not be < 10, but was ${

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