apache/cassandra · info

Detected environment variable

Error message

Detected environment variable {}={} override for Cassandra configuration '{}'.

What it means

Warning from YamlConfigurationLoader.maybeAddEnvironmentVariables when an environment variable following the CASSANDRA_ prefix convention maps to a recognized overridable configuration key. The value overrides cassandra.yaml (after scalar/JSON-tree conversion) and is logged once during initialization (CASSANDRA-9909 flood guard). This makes env-based config explicit at startup.

Solutions

1. If yaml should win, unset the CASSANDRA_* env var in the deployment (remove from container spec / entrypoint).
2. If intentional, no action; but document the precedence: env var > system property context > cassandra.yaml value.
3. Inspect effective configuration at runtime to confirm which value is in force.
4. Standardize config source in container deployments — prefer one mechanism to avoid drift.

Example fix

// before (k8s env)
env: [{name: CASSANDRA_CLUSTER_NAME, value: OverrideName}]
// after
# env removed; cluster_name comes from cassandra.yaml

# list env overrides in effect before start
env | grep '^CASSANDRA_' || echo 'no env overrides'

When it happens

Trigger: Launching with an env var like CASSANDRA_CLUSTER_NAME=prod or CASSANDRA_NATIVE_TRANSPORT_PORT=9042 whose derived configKey is in OVERRIDABLE_CONFIG_NAMES; typical of containerized deployments (Docker/Kubernetes) injecting CASSANDRA_* variables.

Common situations: Docker images and Helm charts setting CASSANDRA_* env vars that silently override mounted cassandra.yaml; operators confused why yaml edits don't take effect; CI environments exporting CASSANDRA_* variables for tests.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• Used environment property variable
• Config contains both old and new keys for the same…
• Configuration entry can not inherit itself.
• Configuration entry inherits non-existing entry .
• data_file_directories must not contain empty entry

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

Appendix: source

Thrown at src/java/org/apache/cassandra/config/YamlConfigurationLoader.java:240

    {
        if (CONFIG_ALLOW_ENVIRONMENT_VARIABLES.getBoolean(CASSANDRA_ALLOW_CONFIG_ENVIRONMENT_VARIABLES.getBooleanOrDefault(false)))
        {
            Map<String, String> orderedEnvironmentMap = new TreeMap<>(System.getenv()); // checkstyle: suppress nearby 'blockSystemPropertyUsage'
            Map<String, Object> overridingProperties = new HashMap<>();
            for (Map.Entry<String, String> env : orderedEnvironmentMap.entrySet())
            {
                String originalKey = env.getKey();
                if (env.getKey().startsWith(ENVIRONMENT_VARIABLE_PREFIX))
                {
                    String configKey = LocalizeString.toLowerCaseLocalized(originalKey.replace(ENVIRONMENT_VARIABLE_PREFIX, "")
                                                                                      .replace(NESTED_CONFIG_SEPARATOR_ENVIRONMENT, NESTED_CONFIG_SEPARATOR));
                    String configValue = env.getValue();
                    if (OVERRIDABLE_CONFIG_NAMES.contains(configKey))
                    {
                        if (configValue != null && !overridingProperties.containsKey(configKey))
                        {
                            if (!DatabaseDescriptor.hasLoggedConfig()) // CASSANDRA-9909: Avoid flooding config during initialization
                                logger.warn("Detected environment variable {}={} override for Cassandra configuration '{}'.", originalKey, configValue, configKey);
                            overridingProperties.put(configKey, getScalarOrJsonTree(configValue));
                        }
                    }
                    else
                    {
                        logger.warn("Used environment property variable {} to override Cassandra configuration but there is no such environment property counter-part to override.", originalKey);
                    }
                }
            }
            if (!overridingProperties.isEmpty())
                updateFromMap(maybeFlattenNestedProperties(overridingProperties), false, obj);
        }
    }

    private static Map<String, Object> maybeFlattenNestedProperties(Map<String, Object> overridingProperties)
    {
        Map<String, Object> copyOfProperties = new HashMap<>(overridingProperties);
        for (Map.Entry<String, Object> entry : overridingProperties.entrySet())

View on GitHub (pinned to 88fd0f6a0e)